Skip to content

Python Virtual Environments

Isolated environments keep each project's dependencies separate from your system Python and from each other. This sheet covers venv (built-in), plus when to reach for uv.

Table of Contents

Installation / Setup

venv ships with Python 3.3+ — no install needed. You need the venv module (on Debian/Ubuntu: sudo apt install python3-venv; on Windows, the full installer includes it).

python -m venv .venv        # create environment in .venv/
OS / shell Activate Deactivate
macOS / Linux (bash, zsh) source .venv/bin/activate deactivate
Windows (cmd) .venv\Scripts\activate.bat deactivate
Windows (PowerShell) .venv\Scripts\Activate.ps1 deactivate

After activation, python and pip point at the environment:

which python     # .../.venv/bin/python   (Windows: where python)
python -m pip install pandas numpy

Core Syntax

Operation Command
Create python -m venv .venv
Create with a specific interpreter python3.12 -m venv .venv
Activate see table above
Check what's installed pip list
Freeze exact versions pip freeze > requirements.txt
Install from file pip install -r requirements.txt
Remove environment rm -rf .venv (or delete the folder)
Verify isolation python -c "import sys; print(sys.prefix)"

Common Operations

Reproduce an environment from requirements

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

Pin your dependencies

pip freeze > requirements.txt

pip freeze includes transitive deps with exact versions — great for reproduction, noisy for humans. Many projects keep two files:

# requirements.in (human-authored)
pandas>=2.0
scikit-learn

# requirements.txt (generated, exact)
pandas==2.2.2
...

Generate the exact file with pip-tools (pip-compile requirements.in) or let uv manage a lockfile automatically.

pip install --user pandas    # installs to ~/.local — global-ish, can conflict

Prefer a venv per project.

Practical Examples

1. Standard project bootstrap

mkdir myproject && cd myproject
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pandas numpy scikit-learn jupyter
pip freeze > requirements.txt
echo ".venv/" > .gitignore

2. Data science env with a GPU

python -m venv .venv
source .venv/bin/activate
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install -r requirements.txt
python -c "import torch; print(torch.cuda.is_available())"

3. Reproduce someone else's project

git clone https://github.com/someone/project && cd project
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Common Patterns

# One command per shell session, then forget about it
source .venv/bin/activate

# Never pollute the venv with dev tooling in prod requirements
pip install -r requirements.txt
pip install -r requirements-dev.txt   # pytest, mypy, pre-commit, ...

# Jupyter kernel bound to the venv
python -m ipykernel install --user --name=myproject --display-name="My Project"

Best Practices

  • Create a venv per project — never install data science packages into system Python.
  • Keep the venv out of git: add .venv/ to .gitignore.
  • Pin versions in requirements.txt; document the Python version too.
  • Use a lockfile (pip-tools, or uv) for fully reproducible installs.
  • Recreate, don't repair — broken env? rm -rf .venv and rebuild from requirements.
  • Activate the venv in your IDE (VS Code: select the interpreter; PyCharm: configure it).
  • Python version matters: create with the exact interpreter you'll deploy with.

Common Mistakes

Mistake Consequence Correct approach
Forgetting to activate Packages go to the wrong Python which python after activating
Committing .venv/ Bloated repo, merge conflicts Add to .gitignore
pip install outside venv System Python polluted Create/activate venv first
Not pinning versions "Works on my machine" pip freeze > requirements.txt
Deleting the venv folder while active Confusing PATH errors deactivate first, then delete
Multiple environments, same packages Disk + confusion Use one env per project; uv caches globally

Troubleshooting

Symptom Cause Fix
command not found: activate Wrong shell syntax / wrong path Windows: .venv\Scripts\activate; POSIX: source .venv/bin/activate
python still system Python Activation failed or env recreated Check sys.prefix; re-activate
externally-managed-environment (Debian/Ubuntu) OS Python is protected (PEP 668) Use a venv (this is the intended path)
Packages install but import fails Different interpreter in the IDE Select the venv interpreter in the IDE
pip missing in venv Very old Python / partial install python -m ensurepip --upgrade
Script shebang points elsewhere Script created in another env Recreate venv or reinstall the script

Official Documentation

Last Updated

2026-09-06 — Initial version.