A virtual environment is not a badge that makes a Python project professional. It is a project-owned boundary: a particular interpreter and package location that can be inspected, discarded, and recreated without depending on whatever happens to be installed globally. Skipping that boundary can feel faster at first, but the missing boundary eventually appears as a confusing import, deployment, or collaboration failure.
This is the failure a virtual environment prevents. Python’s official tutorial explains that different applications may require incompatible versions of the same package, so each application can use a self-contained environment with its own interpreter and installed packages. 1
The incident starts with an invisible dependency
Imagine two projects using the same library:
project-a needs library 1.0
project-b needs library 2.0
If both projects install into the same global Python installation, the last installation can change what the first project imports. The source code did not change, but the runtime did. A global pip install can therefore create a failure whose cause is outside the repository.
The command below is convenient but ambiguous:
pip install requests
Which pip is it? Which Python will import the package? Is it the same interpreter that runs the application? A safer diagnostic makes the relationship visible:
python -m pip --version
python --version
python -c "import sys; print(sys.executable)"
python -m pip asks the selected interpreter to run pip. That avoids one common mismatch where pip belongs to one Python installation and python points to another.
The first repair: create a project-owned environment
From the project directory:
python -m venv .venv
On Unix-like systems, activate it with:
source .venv/bin/activate
On Windows PowerShell, use:
.venv\Scripts\Activate.ps1
The prompt usually changes to show .venv. Confirm the interpreter before installing anything:
python -c "import sys; print(sys.executable)"
python -m pip --version
The venv module creates an isolated directory based on the Python executable used to run the command. The environment does not rewrite your source code and does not make dependencies globally available. It creates a boundary around the project’s interpreter and site-packages.
Activation is a convenience, not a requirement. A script can call .venv/bin/python directly, and a CI job can invoke the environment’s interpreter without changing an interactive shell. This matters when debugging: an activated prompt is evidence, but sys.executable is the stronger proof.
The second repair: separate the environment from the dependency record
A virtual environment is usually not committed to Git. It contains machine-specific files and installed artifacts. The repository should contain a description from which another developer can build a compatible environment.
A simple project may use:
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt
This captures installed versions, but it is not always the best dependency design. A frozen environment can include packages installed for experiments, operating-system-specific packages, or transitive dependencies that the application never imported. For a library or modern application, pyproject.toml can declare project metadata and dependencies. The Python Packaging User Guide documents [build-system], [project], and [tool] tables and recommends a build-system declaration for packaging projects. 2
The important distinction is between direct requirements and a complete lock of resolved artifacts. A direct dependency says what the application needs. A lock or freeze record says what was installed for a particular platform and resolution. Use the format that matches whether you are publishing a package, deploying an application, or teaching a small script.
The post-mortem: why “it works on my machine” survived review
The original project had three hidden assumptions. It assumed that Python was available under the command python. It assumed that the global interpreter contained the package. It assumed that the package API had not changed. None of those assumptions appeared in the repository.
A good repair makes each assumption observable:
python --version
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -c "import package_name; print(package_name.__file__)"
python -m pytest
The import path is especially useful. It reveals whether Python loaded the package from .venv, the user site, a system directory, or the project itself. If a different location appears, the environment boundary is not doing what you think.
A useful companion is sys.path, but read it as evidence rather than editing it blindly:
python -c "import sys; print('\\n'.join(sys.path))"
If a project imports a local module with the same name as a third-party package, the current working directory may also affect resolution. Rename ambiguous files, keep the project layout clear, and test the command from the same directory used in CI. A virtual environment isolates installed packages; it does not correct a confusing import path or a shadowed module.
The Python version itself is part of the incident. A package may install successfully on one interpreter and fail on another because of supported syntax, binary wheels, or standard-library behavior. Record the version intentionally, select it when creating .venv, and make the CI matrix test the versions the project claims to support.
The same problem appears when a shell keeps PYTHONPATH pointing at incompatible code. Python’s tutorial notes that activating a virtual environment does not alter PYTHONPATH; an inherited path can therefore introduce modules from another project. Inspect it when imports seem impossible:
python -c "import os; print(os.environ.get('PYTHONPATH'))"
Rebuilding instead of repairing a contaminated environment
When the environment has accumulated experiments, deletion is often safer than a long sequence of upgrades:
deactivate
rm -rf .venv
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
Do not delete a production environment casually; verify the deployment process and preserve the dependency record first. For local development, however, a disposable .venv makes the repair reproducible. The directory is an output of the setup process, not the source of truth.
This also explains why copying .venv between machines is a poor substitute for rebuilding it. The environment may contain absolute paths, platform-specific wheels, a different interpreter, and files that were never meant to leave the original machine. Recreate it from the repository’s declared inputs and let the installer resolve artifacts for the target platform.
For a team, the repository should answer which Python versions are supported, which command creates the environment, and which command verifies it. If a new developer needs an undocumented global package, the project still has an environmental dependency.
Reproducibility has levels. A requirements file may describe acceptable versions, while a lock file or resolved export records the exact graph used by a deployment. A published library often needs compatible ranges so downstream applications can resolve their own graph; an application deployment may prefer a locked graph so the same build can be recreated. Explain which level the project promises instead of treating every version file as interchangeable.
The environment also belongs in the developer experience. Editors should be pointed at the project interpreter, test commands should use the same interpreter, and pre-commit or lint hooks should not silently run from a global installation. A project can have a correct .venv and still appear broken if the editor or task runner selects another Python.
A .gitignore entry prevents accidental commits:
.venv/
Do not confuse .venv with .env. The first is commonly a directory for Python packages. The second is often a text file containing configuration values. Their names are similar, but their security and lifecycle are different.
What changes in CI and deployment
A continuous-integration job should create the environment from the repository rather than depending on a preconfigured machine.
The setup should also make failure messages useful. Print the interpreter version at the start of a job, fail when dependency installation fails, and run a smoke import before a long test suite. If the project publishes a package, test an installation of the built artifact in a fresh environment instead of testing only the source checkout. That catches missing package data and undeclared runtime requirements.
For local teams, document the one supported setup command and the expected activation command for each shell. Documentation is not a substitute for automation, but it keeps the first environment creation from depending on tribal knowledge. A minimal sequence is:
python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pytest
Calling the interpreter by path avoids activation-shell differences. A deployment image may use a different packaging workflow, but the principle remains: select the Python version, install declared dependencies, run tests, and record the result.
Virtual environments do not solve every reproducibility problem. They do not pin the operating system, native libraries, database version, or external services. They also do not make unsafe packages trustworthy. They solve one specific class of failure: packages and interpreter state leaking between projects.
The Friday-to-Monday incident is therefore not a reason to memorize activation commands. It is a reminder to separate application code, interpreter selection, installed dependencies, and configuration. When those boundaries are visible, a missing import becomes a diagnosable setup problem instead of a mysterious change in the code.
Next step: after isolating the interpreter, read How to Read and Write Files in Python or compare dependency declarations with What Is a Package Manager?.
Know what a virtual environment does and does not isolate
Python’s venv module creates a lightweight environment with its own interpreter-facing package location. By default, packages from the base installation are not available inside it. That is useful isolation, but it is not a container, a secret store, or a complete operating-system boundary. The project still needs a dependency declaration, safe configuration, and a deployment process.
| Question | Evidence to inspect | What the environment can tell you |
|---|---|---|
| Which Python is running? | python -c "import sys; print(sys.executable)" | Whether the command uses the project interpreter. |
| Where will packages install? | python -m pip --version | Which pip and site-packages directory are connected. |
| What does the project declare? | requirements.txt or pyproject.toml | Whether a clean machine can reconstruct dependencies. |
| Can the environment move to another machine? | Recreation command and dependency files | Whether the setup is reproducible; the environment directory itself is not portable. |
| Is the environment active? | Interpreter path, not only VIRTUAL_ENV | Activation is convenient, but using an explicit interpreter is also valid. |
The official documentation describes environments as disposable and generally non-portable; recreate them rather than copying a directory to a new location [1]. This distinction prevents a common mistake: committing .venv while forgetting the dependency record.
Rebuild the boundary instead of patching symptoms
When a project has been contaminated by global packages, create a new environment rather than uninstalling packages until the old one happens to work. On POSIX systems:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txtOn Windows, the activation command differs, but the principle is the same: create the environment with the intended interpreter, activate it for convenience or call its Python directly, then install from a declared dependency set. Confirm the result with python -m pip list and a small import test.
Activation is not the environment
Activation changes shell lookup so that python and installed scripts point to the environment. It does not permanently modify the project, and it is not required when commands use the environment’s full interpreter path. This matters in CI, editors, task runners, and production services, where shell activation may not run.
For related setup, see package managers, environment variables, and reading Python tracebacks. If an import fails, compare the interpreter that installs the package with the interpreter that runs the program before changing versions.
Virtual-environment review checklist
- Create the environment from the interpreter the project intends to use.
- Keep the environment directory out of source control.
- Declare direct dependencies outside the environment directory.
- Use
python -m pipso installation follows the selected interpreter. - Test a clean recreation, not only the developer’s existing machine.
- Recreate rather than copy an environment when the path or machine changes.
A virtual environment pays for itself when it makes a dependency boundary visible. It cannot replace a manifest or deployment discipline, but it prevents many unrelated projects from silently sharing the same package state.
Alex Carter is the editorial name behind Vandutz Academy, a programming blog for beginners. Alex reviews and tests the examples and explanations published on the site, with a focus on making Python, JavaScript, web development, and developer tools easier to understand.