Virtual Environments with venv: Project Isolation Step by Step

Why isolation matters

Imagine two projects on the same machine: one requires requests==2.28 and another needs requests==2.31. If both use the system-wide Python installation, only one version of requests can be installed at a time. Installing the newer version for Project B quietly breaks Project A.

Virtual environments solve this by giving each project its own private copy of site-packages—the directory where pip installs packages. Projects share the same interpreter binary but each gets its own library tree. Upgrading a package in one project has no effect on any other.

Step 1: Create the environment

Navigate to your project directory and run:

python -m venv .venv

This creates a directory called .venv containing a copy of the Python interpreter, pip, and an empty site-packages folder. The leading dot keeps it hidden in most directory listings. You can name it anything; .venv and venv are both common conventions.

To use a specific Python version, point to that interpreter directly:

python3.12 -m venv .venv

Step 2: Activate the environment

Activation modifies the current shell session so that python and pip resolve to the versions inside .venv:

1. Linux / macOS: source .venv/bin/activate
2. Windows (cmd.exe): .venv\Scripts\activate.bat
3. Windows (PowerShell): .venv\Scripts\Activate.ps1

After activation, your shell prompt shows the environment name in parentheses: (.venv) $. Running which python (Linux/macOS) or where python (Windows) confirms it points inside .venv.

To leave the environment, type deactivate.

Step 3: Install packages

With the environment active, pip installs into the local site-packages, not the system:

pip install requests pandas
pip install "flask>=3.0"

Nothing installed here can affect other projects or the system Python. You can install conflicting versions in different environments without issue.

Step 4: Freeze and reproduce

To share exact dependency versions with teammates or a deployment environment, generate a requirements file:

pip freeze > requirements.txt

The file lists every installed package and its pinned version. To recreate the environment on another machine:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Add .venv/ to your .gitignore file. The environment directory is large, machine-specific, and entirely reproducible from requirements.txt, so it does not belong in version control.

Common problems and fixes