1. Define the reference and the expected result
Start with what you want to reproduce: produce the same categories, obtain close values or resume a training trajectory. Keep a small set of inputs that goes through the important steps, plus an example of valid output. An installation that finishes without errors does not yet answer that question.
Take a teaching example: your application produces embeddings for an identified sample. On the reference environment, you need to note the shape of the outputs, their type, the absence of non-finite values, and the useful business criterion. If you compare values, choose a tolerance justified by your use case. No universal numeric threshold is provided here.
Assign a revision to the code, the data, and the weights. A name like "latest-model" can change without the program showing it. Also associate the parameters and the preprocessing with the reference. This record makes it possible to know whether a difference comes from the software, the inputs, or the execution conditions.
Scroll the table to read all columns.| Item | To keep | Check after reconstruction |
|---|---|---|
| Code and parameters | Revision, any modifications, configuration | Same entry point and same options. |
| Data and weights | Version or hash, provenance, and access rights | Same sample and same expected content. |
| Python and packages | Versions, procedure, and installation sources | Correct interpreter and consistent dependencies. |
| System and backend | OS, architecture, driver, CUDA or ROCm | Visible device and minimal successful computation. |
| Result | Format and acceptance criteria | Structure, then quality or expected tolerance. |
2. Separate the system stack from the Python packages
Verify the card, the system, the driver, Python, and the libraries together. A virtual environment organizes Python packages; it does not replace the system driver. Likewise, the reference of an image is not enough to describe the actual access to the GPU from its host. For a compiled extension, record the required build tools and libraries.
Choose the PyTorch distribution based on your project's compute platform. On ROCm, PyTorch reuses the torch.cuda calls and the devices named cuda: the name of the interface does not identify NVIDIA. Record torch.version.cuda and torch.version.hip separately. An extension written for a given stack deserves its own check.
Keep the procedure that actually enabled the installation, along with the origin of the packages. Avoid mixing a recent command found online with an old dependency file without examining their compatibility. The documentation you consult may change; write down the versions used in your own record.
3. Write a reconstruction rather than copying the installed folder
Create a new environment with the chosen Python. Then explicitly use its interpreter to install and run the project. On Linux, this will be, for example, .venv-rebuild/bin/python; on Windows, .venv-rebuild\Scripts\python.exe. You don't need to depend on a prior activation. The Python documentation states that a virtual environment must be recreated when it changes location.
pip freeze provides an inventory of installed packages, not a computed lock file. Keep it as an observation. The reconstruction file must also make explicit the indexes or files needed for your PyTorch variant and the compatible versions. Review the paths or URLs that an inventory might contain before sharing it.
The commands below illustrate a Linux reconstruction to be adapted; they are not a tested run of your project. The requirements-rebuild.txt file must already describe your environment, including the correct choice of PyTorch. Do not replace it with a list of versions assumed to be universal.
python -m venv .venv-rebuild
.venv-rebuild/bin/python -m pip --version
.venv-rebuild/bin/python -m pip install -r requirements-rebuild.txt
.venv-rebuild/bin/python -m pip check
.venv-rebuild/bin/python -m pip freeze --all > installed-after.txt4. Verify the dependency contract before computation
python -m pip check, run with the correct interpreter, looks for installed dependencies that are missing or incompatible according to their metadata. A result with no conflicts is not a validation of the driver, the native extensions, or the quality of the application. So keep this step short and move on to a computation check.
To make the reconstruction more strict, you can pin versions and keep the hashes of authorized distributions. This decision requires maintaining the complete list that matches your platform. An archive of compiled wheels can depend on the OS and architecture; it is not a guarantee of portability between two different machines.
In our embeddings example, compare the reconstructed inventory against the reference before modifying the model or its parameters. If a difference is intentional, note it and treat the new run as a variant. Otherwise, fix the reconstruction; changing several layers at once will make the diagnosis less precise.
5. Moving from minimal check to application
In the project interpreter, note the Python, PyTorch and backend versions, then check the device and a small computation. Stop at this step if the expected GPU is not accessible; a CPU fallback run would blur the comparison. The Kernodeck diagnostic provides an interpretable report and distinguishes the steps actually completed.
Once this check succeeds, use your small application sample. For embeddings, verify the number of outputs, their dimensions, their correspondence with the identifiers and the chosen criterion. Reload the files from the output folder. A successful matrix computation does not prove that the preprocessing or a project extension works.
If the trial crashes while reading the data, during a transfer or during a specific operation, keep the step and the first error. The general reconstruction may be correct; the blockage may belong to the data loader or to a particular operator. Then direct the diagnosis toward that layer.
6. Distinguishing reconstruction from numerical identity
Recovering the same dependencies does not guarantee identical results across hardware, platforms or PyTorch versions. Setting a seed does not cover all sources of variation. Document the generators used, the data transformations and the relevant precision or determinism settings.
Define the comparison criterion before looking at the difference: exact structure, numerical tolerance or stability of a metric. Some deterministic settings may reject operations or change the computational cost. The desired result is a conclusion that is understandable under the stated conditions, not a promise of identity on any machine.
For resuming training, versions alone are not enough: you also need to restore the computation state and progress. The resumption folder examines this question separately. Its CPU exercise and its tolerance do not automatically become the conditions of your model.
7. Finish with a folder that another run can use
The final folder brings together the procedure, the observed inventory, the configuration, the data references and the check results. Add the exact sequence: reconstruct, diagnose, run the sample, review the output. Keep access credentials separate and specify only how to provide them.
Replay this sequence in a clean folder before considering the environment transferable. The check must succeed without retrieving a variable from an old notebook or looking for a forgotten file. If a change is necessary, fix the procedure and give the reference a new identity. You get a usable basis for your next compute period.