Skip to content

Virtual Environments

Virtual environments are the foundation of every reliable Python project. The handbook explains what a venv is, why you need one, and how to manage Python interpreters and isolated environments with modern tools.

Concepts

What is a virtual environment
The core concept explained
Why use one
Why isolation matters
Avoid system Python
What can go wrong if you don’t

Tools

uv
The modern way: uv manages venvs and Python versions in one tool
pyenv
Install and switch Python versions
venv
The standard library module
virtualenv
The original third-party tool

Migration paths

From pyenv to uv
Replace pyenv with uv
pyenv vs uv
Two ways to manage Python versions

More Virtual Environments pages

Everything else tagged virtual-environments, grouped by section. Pages featured above are not repeated here.

How To

How to Cache uv Dependencies in CI

Cache uv's package store and managed interpreters in CI to skip re-downloads, and keep .venv out so stale packages never survive a restore.

How to configure Claude Code to use virtual environments

Make Claude Code use virtual environments via `uv run`, CLAUDE.md rules, env config, or PreToolUse hooks. Shell activation doesn't persist.

How to create and use a Python virtual environment with venv

Create and activate a Python virtual environment with venv on macOS, Linux, and Windows. Includes activation syntax and troubleshooting.

How to customize uv's virtual environment location

Override uv's default .venv location using UV_PROJECT_ENVIRONMENT environment variable or the --active flag to use an existing virtual environment.

How to Fix "zsh: command not found: python" on macOS

Fix zsh: command not found: python on macOS by running python3 for a quick check or installing uv to manage Python and put it on PATH.

How to Fix ModuleNotFoundError: No Module Named 'package'

Find which of five causes broke your import in one command, so the package you installed finally imports.

How to Fix pyenv's "No module named '_lzma'" Error

Fix a pyenv Python missing the lzma module by installing xz and rebuilding the interpreter, or skip source compilation with uv.

How to fix the "externally-managed-environment" error

Fix the externally-managed-environment error on Linux. Use virtual environments or uv tool install instead.

How to Inspect a Virtual Environment You Did Not Create

Read the dependency tree of an existing virtualenv with uv pip tree to learn what is installed and which package pulled it in.

How to Install Python (and Which Method to Choose)

Install Python with uv on macOS, Windows, or Linux, and let one tool manage versions so every project gets the right one.

How to Install Python on macOS

Install Python on macOS with uv instead of the system python3 or Homebrew, so pip stops failing and versions stay current.

How to Install Python on Windows

Install Python on Windows with uv or python.org. Stop the Microsoft Store from hijacking python and get a real interpreter on your PATH for development.

How to Migrate from conda to uv

Convert a conda environment to a uv project with pyproject.toml and uv.lock for reproducible installs that finish in seconds.

How to require a virtualenv when installing packages with pip?

Configure pip to refuse package installation outside a virtual environment using PIP_REQUIRE_VIRTUALENV.

How to use pip in a uv virtual environment

Add pip to a uv virtual environment. Support Jupyter %pip magic and tools that require direct pip access.

How to use uv on NixOS

Install uv on NixOS, fix the dynamic-linker error that breaks managed Python downloads, and pin uv per project with a flake.nix dev shell.

Explanation

Do I need a project to use uv?

uv works without a project directory. Here are options for using uv with single-file scripts, script collections, and when each approach makes sense.

Should I use Homebrew to install Python?

Homebrew's Python exists to support other Homebrew tools and can break unexpectedly on upgrade. Use uv to manage Python instead.

What is a .python-version file?

.python-version: specify your project's Python version. Tools like uv and pyenv auto-switch when you cd into the directory.

What is PEP 668?

PEP 668 marks system Python installations as externally managed, causing pip to refuse package installation outside a virtual environment.

Reference

direnv

direnv: loads/unloads environment variables per directory. Activate Python venvs and manage project settings without global pollution.

mise

mise is a cross-platform CLI that manages multiple language runtimes, environment variables, and tasks per project from a single mise.toml manifest.

pipdeptree

pipdeptree renders installed packages as a dependency tree, revealing which package pulled in each transitive dependency.

pyenv-virtualenv

pyenv-virtualenv is a pyenv plugin for creating and auto-activating virtual environments tied to specific Python versions.

From the blog

Posts tagged virtual-environments.

Last updated on