venv

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.

Creating Environments

# Create a virtual environment in the .venv directory
python -m venv .venv

# Create with a specific Python version (if available on PATH)
python3.12 -m venv .venv

# Create without pip pre-installed (faster, smaller)
python -m venv --without-pip .venv

# Create with access to system site-packages
python -m venv --system-site-packages .venv

# Reset an existing environment to a clean state
python -m venv --clear .venv

The --without-pip flag is useful when using an external installer like uv to manage packages instead of pip.

Activation

Activating a virtual environment modifies the shell’s PATH so that the environment’s Python interpreter and installed packages take precedence over the system installation.

# macOS / Linux (bash/zsh)
source .venv/bin/activate

# macOS / Linux (fish)
source .venv/bin/activate.fish

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

# Windows (cmd)
.venv\Scripts\activate.bat

After activation, python and pip resolve to the environment’s copies. Run deactivate to restore the original shell state.

What venv Creates

A typical .venv directory contains:

.venv/
├── bin/               # (Scripts/ on Windows) interpreter, pip, activate scripts
├── include/           # C header files for building extensions
├── lib/
│   └── pythonX.Y/
│       └── site-packages/   # installed packages go here
└── pyvenv.cfg         # environment configuration

The pyvenv.cfg file records the base Python path, version, and whether system site-packages are included. Most tools that detect virtual environments read this file.

Common Workflow

# Create and activate
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Work on the project
python main.py

# Freeze current state
pip freeze > requirements.txt

# Deactivate when done
deactivate

With uv, this entire sequence reduces to:

uv run main.py

uv creates the environment, installs dependencies from pyproject.toml, and runs the command in a single step. See Create your first Python project for a walkthrough.

Limitations

• No dependency locking — venv creates environments but does not resolve or lock dependencies. That responsibility falls to pip, pip-tools, or uv.
• No Python version management — venv can only use Python interpreters already installed on the system. Tools like pyenv or uv handle installing new Python versions.
• Slower than alternatives — virtualenv and uv both create environments faster by using seed caches and hardlinks.
• No cross-platform lockfiles — reproducible multi-platform builds require additional tooling.

Learn More

• venv documentation
• What is a Virtual Environment?
• Install packages in a virtual environment using pip and venv
• Python Virtual Environments: A Primer