📦 Python Virtual Environments

The Dependency Problem

Suppose Project A needs Django 3.2 and Project B needs Django 4.2. If you pip install Django globally, only one version can exist at a time — installing one silently breaks the other. Scale that to dozens of packages across many projects and you get "dependency hell."

There's a second, sharper reason to avoid installing into the system Python: on Linux and macOS the operating system itself depends on that Python. Modern Python even blocks global installs with an "externally-managed-environment" error to stop you from breaking your OS. Virtual environments are the sanctioned way out.

What Is a Virtual Environment?

A virtual environment is a self-contained directory holding a specific Python interpreter and its own independent set of installed packages, isolated from other environments and from the system Python.

💡 Analogy: Think of each project getting its own kitchen. Without virtual environments, every chef shares one kitchen and fights over the same stove and ingredients. With them, each chef gets a private kitchen stocked with exactly what their recipe needs — no conflicts, no compromises.

Using venv (Built-in)

Since Python 3.3, the venv module ships with Python — no installation required. It's the right default for most projects. The convention is to name the folder .venv so editors like VS Code detect it automatically.

# Create an environment in a folder named .venv
python -m venv .venv

# Activate it — macOS / Linux
source .venv/bin/activate

# Activate it — Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Activate it — Windows (cmd.exe)
.venv\Scripts\activate.bat

# Your prompt now shows (.venv). Install packages into it:
pip install flask

# When you're done working in this project:
deactivate

How Activation Works

"Activation" sounds magical, but it's simple. The activate script does three things to your current shell:

1. Edits PATH: it prepends the environment's bin (or Scripts on Windows) directory, so python resolves to the environment's interpreter first.
2. Changes the prompt: it adds a (.venv) prefix so you can see which environment is active.
3. Sets VIRTUAL_ENV: an environment variable tools use to detect the active environment.

Nothing is permanently installed by activation, and it only affects the current terminal. deactivate simply restores the original PATH and prompt.

.venv/
├── bin/              # Scripts/ on Windows
│   ├── activate      # the activation script
│   ├── python        # this env's interpreter (symlink/copy)
│   └── pip           # this env's pip
├── lib/pythonX.Y/site-packages/   # installed packages live here
└── pyvenv.cfg        # points back to the base Python

The Tool Landscape

Several tools create environments. Here's how the main ones compare — and when to reach for each.

The same task in three tools

# venv (built-in)
python -m venv .venv && source .venv/bin/activate

# conda
conda create --name myenv python=3.12
conda activate myenv

# uv (fast, modern)
uv venv                 # creates .venv
source .venv/bin/activate
uv pip install flask

Sharing Dependencies

A teammate can't use your environment folder — but they can rebuild an identical one from a recorded list. The classic mechanism is requirements.txt.

# Record everything currently installed (exact versions)
pip freeze > requirements.txt

# On another machine, recreate the environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# requirements.txt — direct dependencies only
Django>=4.2,<5.0
requests>=2.28.0
python-dotenv>=1.0.0

Lock files: the modern answer

For fully reproducible builds you want a lock file that pins exact versions (and hashes) of the entire dependency tree, separate from your high-level requirements:

• Poetry — pyproject.toml (what you want) + poetry.lock (exactly what's installed).
• uv / pip-tools — compile a requirements.in into a fully-pinned requirements.txt.

# pyproject.toml (Poetry excerpt)
[tool.poetry.dependencies]
python = "^3.12"
django = "^4.2"
requests = "^2.28.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.3"
black = "^23.3"

import os
from dotenv import load_dotenv

load_dotenv()  # reads .env into os.environ
DEBUG = os.getenv("DEBUG", "False").lower() == "true"
DB_URL = os.getenv("DATABASE_URL")

Hands-on Exercise

mkdir venv_lab && cd venv_lab

# Environment 1 — older requests
python -m venv env_old
source env_old/bin/activate         # Windows: env_old\Scripts\activate
pip install "requests==2.25.1"
python -c "import requests; print('env_old:', requests.__version__)"
pip freeze > requirements-old.txt
deactivate

# Environment 2 — newer requests
python -m venv env_new
source env_new/bin/activate
pip install "requests==2.31.0"
python -c "import requests; print('env_new:', requests.__version__)"
pip freeze > requirements-new.txt
deactivate

Best Practices & Troubleshooting

Summary & Quiz

📚 Further Reading

• Python venv Documentation
• uv Documentation
• Poetry Documentation
• Real Python — Virtual Environments Primer

🚀 What's Next?

Now that you have a clean place to install things, let's master the tool that installs them. Next: Python Package Management with pip — PyPI, version specifiers, requirements files, and security.