Python Developer Tooling Handbook – Virtual Environments

direnv: Per-Directory Environment Variables for Python

Tim Hopper — Thu, 30 Apr 2026 07:12:25 -0400

direnv is a shell extension that loads and unloads environment variables based on the current working directory. It reads a per-directory .envrc file when entering a folder and reverts the environment when leaving. Although direnv is language-agnostic, it is widely used in Python projects to activate virtual environments and export project-specific settings without polluting the global shell.

Key Features

Loads variables from .envrc on cd into a directory and unloads them on cd out
Provides a stdlib of layout helpers, including layout python, layout python3, layout pyenv, and layout pipenv
Supports bash, zsh, fish, tcsh, elvish, and PowerShell
Requires explicit per-directory authorization with direnv allow before any new .envrc runs

Installation

direnv is distributed through most package managers:

Do I need a project to use uv?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

If your Python life is a folder full of short scripts that glue APIs together and rename files, uv’s first move can look like overkill: uv init, then a pyproject.toml. uv works fine for scripts, but it assumes a different mental model from the pip install habit most script authors carry, and forcing the old habit onto uv is where people get stuck.

The short answer: no, you don’t need a project. You have four options, and the right one depends on what the script is.

How do pyenv and uv compare for Python interpreter management?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

pyenv manages Python versions and gets out of the way; uv manages Python versions as part of controlling your entire workflow. That difference in scope shapes every other trade-off between the two tools.

Design Philosophy

pyenv

pyenv embodies the Unix principle of “do one thing well.” Its sole purpose is managing Python interpreter installations and version switching. This focused approach means pyenv integrates seamlessly with existing workflows; after selecting a Python version, developers use familiar tools like pip and venv for package management and virtual environments.

How to configure Claude Code to use virtual environments

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Claude Code starts a fresh shell for every Bash tool call, so source .venv/bin/activate in one command has no effect on the next. Without configuration, Claude reaches for system Python and installs packages outside the project’s virtual environment. Four configuration patterns work around the stateless-shell limitation:

uv run for projects on uv, which sidesteps activation entirely
A CLAUDE.md instruction that tells Claude to call the venv’s interpreter directly
A .claude/settings.json env block that pre-sets VIRTUAL_ENV and PATH for every session
A PreToolUse hook that blocks bare python and pip so the rules are enforced, not just suggested

Trace why `source activate` doesn’t persist

Each Bash tool call Claude Code runs spawns a separate shell process. Environment changes made by source .venv/bin/activate (it sets VIRTUAL_ENV and prepends .venv/bin to PATH) live only inside that shell. When the next tool call starts a new shell, those variables are gone.

How to create and use a Python virtual environment with venv

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

A README says “create a virtual environment” before it tells you what that means. Use Python’s built-in venv module to create one, activate it, and install packages into the right place. For the concepts, see What is a virtual environment?. For a new project from scratch, uv handles all of this for you.

Create the environment

Run this from your project directory:

python3 -m venv .venv

py -m venv .venv

If Windows does not recognize py, use python -m venv .venv instead.

How to customize uv's virtual environment location

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

When working with uv projects, the virtual environment is automatically created in a folder called .venv in your project directory.

your-project/
├── pyproject.toml
├── .venv/          # Virtual environment location
└── src/

You can override this default with a flag or a environmental variable.

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

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Running pip install on a system Python protected by PEP 668 produces this error:

error: externally-managed-environment

× This environment is externally managed

The fix depends on what was being installed.

Installing project dependencies

Use uv to create a project with its own virtual environment:

How to require a virtualenv when installing packages with pip?

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

By default, pip allows installing packages into the global Python environment. This can lead to dependency conflicts and break system tools. Configuring pip to require a virtual environment prevents accidental global installs.

Using an environment variable

Set the PIP_REQUIRE_VIRTUALENV environment variable to true in your shell profile (e.g. ~/.bashrc, ~/.zshrc):

export PIP_REQUIRE_VIRTUALENV=true

With this set, running pip install outside a virtual environment produces an error:

How to switch from pyenv to uv for managing Python versions

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

This guide shows how to transition from using pyenv to uv for managing Python versions. While pyenv has been a reliable tool for many years, uv offers faster performance and more integrated workflows.

Steps to Switch

1. Remove pyenv Integration From Shell

Remove pyenv initialization from your shell configuration files:

Open your shell configuration file (.bashrc, .zshrc, etc.)
Remove or comment out lines like:

eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Reload your shell configuration:

source ~/.bashrc  # or .zshrc, etc.

2. Clean Up pyenv Installation

Remove pyenv from your system:

How to use pip in a uv virtual environment

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

Only add pip to uv environments when specifically needed for compatibility with tools that directly call pip. For regular package management, continue using uv commands (uv add/uv sync), which offer better performance and reliability.

When working with uv, you might occasionally need access to pip in your virtual environments, particularly when using tools that rely on pip directly, such as Jupyter’s %pip magic command.

How to use uv on NixOS

Tim Hopper — Wed, 13 May 2026 06:43:22 -0400

uv ships as a single static binary that drops onto NixOS without a build step. The hard part is what happens next: uv’s managed Python interpreters are precompiled for a generic Linux that NixOS doesn’t pretend to be, so uv sync and uv run fail with Could not start dynamically linked executable until you bridge the gap.

This guide walks through the two patterns NixOS users reach for: enabling nix-ld system-wide so uv-downloaded Python binaries find their dynamic linker, and pinning uv inside a flake.nix dev shell that sets LD_LIBRARY_PATH per project. Pick one based on whether you want uv to work everywhere on your system or only inside specific repositories.

pyenv: Python Version Manager

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

pyenv is a command-line tool for installing, managing, and switching between multiple Python interpreter versions on macOS and Linux. It intercepts Python commands through shell shims, routing them to whichever interpreter version is active for the current directory, user, or system.

When to use pyenv

pyenv fits workflows where Python version management should remain separate from package management. It pairs with pip, venv, or any other packaging tool without imposing opinions on how dependencies are managed. If you want a single tool that also handles dependencies and virtual environments, uv covers version management alongside those workflows.

pyenv-virtualenv: Python Virtual Environment Plugin

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

pyenv-virtualenv is a plugin for pyenv that creates and manages virtual environments tied to specific Python versions. It extends pyenv with a pyenv virtualenv command and hooks into shell initialization so the right environment activates whenever a directory’s .python-version file names it.

When to use pyenv-virtualenv

pyenv-virtualenv fits teams already running pyenv who want directory-scoped virtual environments without changing version managers. The plugin pairs with pip or any other installer because it only handles environment creation and activation. Teams looking for a single tool that combines Python version management, virtual environments, lockfiles, and dependency resolution may prefer uv. For pyenv users moving to uv, see How to switch from pyenv to uv for managing Python versions.

Should I use Homebrew to install Python?

Tim Hopper — Mon, 04 May 2026 08:02:03 -0400

Homebrew ships Python because dozens of its own packages depend on it. Tools like glib, cmake, and awscli all pull in Python as a build or runtime dependency. When Homebrew installs Python, it is satisfying its own dependency graph, not setting up a development environment for you.

This distinction matters because Homebrew treats Python the same way it treats any other dependency: as something to keep current. Running brew upgrade can bump Python from 3.12 to 3.13 without warning, removing the previous minor version’s site-packages directory in the process.

venv: Python Built-in Virtual Environment Module

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

venv is Python’s built-in module for creating virtual environments. Included in the standard library since Python 3.3, it creates lightweight, isolated directory trees containing a Python interpreter and a dedicated site-packages directory for project-specific dependencies.

When to use venv

venv fits any project that needs an isolated Python environment using only the standard library, with no extra installs or dependencies to vet. It is the default choice on Python 3.3 or later when a third-party tool like virtualenv or uv cannot be added (locked-down systems or minimal CI images that ship Python and nothing else). For new work where third-party tools are available, uv creates and manages virtual environments automatically through uv run and uv sync, removing the manual create-and-activate steps venv requires.

virtualenv: Python Virtual Environment Tool

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

virtualenv creates isolated Python virtual environments. Virtual environments are self-contained directories that contain a Python installation for a particular version of Python, plus additional packages.

When to use virtualenv

virtualenv fits projects that need broader Python version support than the standard library’s venv module offers, or that benefit from its faster environment creation through cached seed packages. Most modern projects on Python 3.3 or later can use venv, which ships in the standard library and covers the same core workflow without an extra dependency. For new work, uv creates and manages virtual environments automatically as part of its run and sync commands, removing most of the manual steps either tool requires.

What is a .python-version file?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

A .python-version file is a simple text file that specifies which Python version should be used for a particular project or directory. When present, Python version management tools like uv and pyenv automatically use the specified Python version when working in that directory.

The file contains a single line with a Python version specification, e.g.,

3.11.5

This approach provides environment-specific Python version control without requiring manual activation or configuration each time you work on a project.

What is a Virtual Environment?

Tim Hopper — Tue, 28 Apr 2026 21:54:51 -0400

A virtual environment is an isolated Python runtime environment that enables development with project-specific dependencies and Python versions without interference from other projects or the system Python installation.

Think of a virtual environment like a clean workshop for each project. Instead of having all your tools mixed in one garage (which could lead to version conflicts or missing dependencies), each project gets its own dedicated space with precisely the tools it needs.

Without virtual environments, several critical problems emerge when installing Python packages globally:

What is PEP 668?

Tim Hopper — Tue, 07 Apr 2026 14:40:41 -0400

If pip has ever refused with error: externally-managed-environment, that was PEP 668 at work.

PEP 668 (“Marking Python base environments as externally managed”) defines a mechanism for OS distributors to protect their Python installations from accidental modification by pip. Accepted in June 2022, it has since been adopted by major Linux distributions and by Homebrew on macOS.

Why it exists

Operating systems install Python packages into a shared site-packages directory. System tools depend on those packages being specific versions. Running pip install into that same directory can overwrite OS-managed files, breaking utilities like apt on Debian or dnf on Fedora. Before PEP 668, nothing stopped users from doing this by accident. For more background, see Why should I avoid using the system Python?.

Why should I avoid using the system Python?

Tim Hopper — Wed, 22 Apr 2026 16:51:52 -0400

The “system Python” is the Python interpreter that ships with your operating system. On macOS and most Linux distributions, it lives at /usr/bin/python3. Windows doesn’t ship Python by default, but a system-wide install from python.org or the Microsoft Store fills the same role and runs into most of the same problems.

This interpreter exists for the operating system, not for development work. Using it for your own projects causes three categories of problems.

Why should I use a virtual environment?

Tim Hopper — Tue, 05 May 2026 06:54:22 -0400

A virtual environment is an isolated Python runtime environment that allows you to work on different Python projects with different dependencies without conflicts. Virtual environments are fundamental to Python development.

The Problem Virtual Environments Solve

Real-world analogy

Think of a virtual environment like a clean workshop for each project. Instead of having all your tools mixed together in one garage (which could lead to version conflicts or missing dependencies), each project gets its own dedicated space with exactly the tools it needs.

When you install Python packages globally (directly into your system Python), several problems arise:

Python Developer Tooling Handbook – Virtual Environments

direnv: Per-Directory Environment Variables for Python

Key Features

Installation

Do I need a project to use uv?

How do pyenv and uv compare for Python interpreter management?

Design Philosophy

pyenv

How to configure Claude Code to use virtual environments

Trace why source activate doesn’t persist

How to create and use a Python virtual environment with venv

Create the environment

How to customize uv's virtual environment location

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

Installing project dependencies

How to require a virtualenv when installing packages with pip?

Using an environment variable

How to switch from pyenv to uv for managing Python versions

Steps to Switch

1. Remove pyenv Integration From Shell

2. Clean Up pyenv Installation

How to use pip in a uv virtual environment

How to use uv on NixOS

pyenv: Python Version Manager

When to use pyenv

pyenv-virtualenv: Python Virtual Environment Plugin

When to use pyenv-virtualenv

Should I use Homebrew to install Python?

venv: Python Built-in Virtual Environment Module

When to use venv

virtualenv: Python Virtual Environment Tool

When to use virtualenv

What is a .python-version file?

What is a Virtual Environment?

What is PEP 668?

Why it exists

Why should I avoid using the system Python?

Why should I use a virtual environment?

The Problem Virtual Environments Solve

Trace why `source activate` doesn’t persist