Rebuilding Python Environments with venv and pip in a Traceable Way

When a small office takes over a Python application or sets up a new computer, the application’s package inventory should be traceable. With venv and pip, you can prepare for a controlled rebuild. A clean starting environment, checked dependencies and application tests are essential. A package export alone does not guarantee universal reproducibility.

1. Define the prerequisites and working directory

All the following Unix examples must be used exclusively in a separate test project, not in the production application directory. A maintained Python interpreter that is already installed and compatible with the project is required. Document the following beforehand:

  • the intended interpreter version, including the minor version,
  • the operating system and processor architecture,
  • the project revision, required configuration and available application tests.

python3 here refers to this deliberately selected interpreter. Check which interpreter it points to before starting; use its explicit path if necessary. Do not replace the operating system’s Python or change the global PATH. All relative paths refer to the root directory of the test project. Filenames such as requirements-snapshot.txt are arbitrarily chosen examples and must be updated consistently if changed.

2. Prepare a clean source environment

Create a separate, initially clean environment for the intended project revision:

python3 -m venv .venv-src

Install only the dependencies intended for the test project in that environment, following the project’s installation instructions. Explicitly use .venv-src/bin/python -m pip to avoid accidentally targeting another environment. Do not adopt an unchecked collection of packages from a shared working environment, and do not perform blanket package upgrades.

According to the venv documentation, project packages are isolated by default. However, the environment remains tied to its base interpreter and is not a security sandbox. Activation is not required when using explicit interpreter paths. Now test the application with suitable test data; export the package list only after that.

3. Capture and check the tested package state

.venv-src/bin/python -m pip freeze > requirements-snapshot.txt

pip freeze reports installed packages. It is not a lockfile solver and omits certain bootstrap packages by default. The file is therefore a starting snapshot, not a complete description of the interpreter, tools and platform.

Open the export before sharing it with anyone. In particular, check editable installations, local paths and private package URLs. Remove credentials from files you share. At the same time, establish how required private packages will remain accessible with authorization; simply deleting those entries does not make the rebuild complete. Record both direct and transitive dependencies rather than listing only the libraries used directly.

4. Rebuild independently and verify

Leave .venv-src unchanged. Create a second environment alongside it using a suitable, compatible interpreter, and install the checked list:

python3 -m venv .venv-rebuild
.venv-rebuild/bin/python -m pip install -r requirements-snapshot.txt
.venv-rebuild/bin/python -m pip check

pip check checks only declared dependency compatibility. A result showing no issues is no substitute for application tests or a security audit. Therefore, perform the same functional checks as in the source environment: for example, an intended import, a typical processing run and a check of the results. Explicitly run these checks with .venv-rebuild/bin/python as well. Document errors and test results before accepting the rebuild.

5. Document the platform and package files in greater detail

For greater traceability, also record the versions of Python and pip used, along with the operating system and architecture. According to the pip guide to repeatable installations, fully pinned direct and transitive dependencies, together with verified package hashes, can provide additional safeguards for the process. Hashes confirm that package files match what is expected, not that they are free of malware. Wheel archives can be platform-specific; a package state available on a different architecture is therefore not automatically equivalent.

6. Secure a way back and record the outcome

Keep the existing environment and a backup of the application and data until the new setup has been verified. If errors occur, discard only the new test environment and investigate the cause; the existing working setup remains untouched. Virtual environments are recreated, not moved or copied.

Conclusion: A usable rebuild consists of a checked package export, a documented platform and successful application tests. This combination makes changes traceable without mistaking a package list for a comprehensive guarantee of reproducibility.