# venv: Python Built-in Virtual Environment Module


venv is Python's built-in module for creating [virtual environments](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md). 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.

## venv vs virtualenv vs uv

All three tools create isolated environments; they differ in what else they manage and what they cost to install.

| | venv | virtualenv | uv |
|---|---|---|---|
| Distribution | Standard library (Python 3.3+) | PyPI package | Standalone binary |
| Extra install | None | `pip install virtualenv` | One binary download |
| Manual activation | Required | Required | Not required (`uv run`) |
| Creation speed | Baseline | Faster (cached seed packages) | Fastest (hardlinked cache) |
| Interpreter support | The invoking CPython 3 | CPython 2 and 3, PyPy | CPython, downloaded on demand |
| Installs Python versions | No | No | Yes |
| Dependency resolution and locking | No | No | Yes |

venv is the zero-install baseline for any project on Python 3.3 or later. [virtualenv](https://pydevtools.com/handbook/reference/virtualenv.md) adds faster creation and support for legacy interpreters like Python 2 and PyPy. [uv](https://pydevtools.com/handbook/reference/uv.md) subsumes both: it creates environments automatically, and it also resolves and locks dependencies and manages Python versions, so `uv run` replaces the manual create-activate-install cycle.

## 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](https://pydevtools.com/handbook/reference/virtualenv.md) or [uv](https://pydevtools.com/handbook/reference/uv.md) cannot be added (locked-down systems or minimal CI images that ship Python and nothing else). For context on why isolation matters, see [Why should I use a virtual environment?](https://pydevtools.com/handbook/explanation/why-should-i-use-a-virtual-environment.md) For new work where third-party tools are available, [uv](https://pydevtools.com/handbook/reference/uv.md) creates and manages virtual environments automatically, installs packages faster, and handles Python version management, removing the manual create-and-activate steps venv requires.

## Maintenance status

venv is not deprecated. It has been the recommended way to create virtual environments since Python 3.5 and remains actively maintained in the CPython standard library. Recent releases refined it: Python 3.9 added the `--upgrade-deps` flag, and Python 3.12 stopped installing `setuptools` by default, leaving only `pip`. venv is sometimes confused with `pyvenv`, a standalone script removed in Python 3.8 and replaced by running `python -m venv` directly.

## Creating Environments

```bash
# 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](https://pydevtools.com/handbook/reference/uv.md) to manage packages instead of [pip](https://pydevtools.com/handbook/reference/pip.md).

## 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.

```bash
# 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.

> [!TIP]
> [uv](https://pydevtools.com/handbook/reference/uv.md) skips activation entirely. `uv run` detects and uses the project's virtual environment without requiring an explicit `source` step.

## 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

```bash
# 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](https://pydevtools.com/handbook/reference/uv.md), this entire sequence reduces to:

```bash
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](https://pydevtools.com/handbook/tutorial/create-your-first-python-project.md) for a walkthrough.

## Limitations

- No dependency locking. venv creates environments but does not resolve or lock dependencies. That responsibility falls to [pip](https://pydevtools.com/handbook/reference/pip.md), [pip-tools](https://pydevtools.com/handbook/reference/pip-tools.md), or [uv](https://pydevtools.com/handbook/reference/uv.md).
- No Python version management. venv can only use Python interpreters already installed on the system. Tools like [pyenv](https://pydevtools.com/handbook/reference/pyenv.md) or uv handle installing new Python versions.
- Slower than alternatives. [virtualenv](https://pydevtools.com/handbook/reference/virtualenv.md) 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

- [How to create and use a Python virtual environment with venv](https://pydevtools.com/handbook/how-to/how-to-create-and-use-a-python-virtual-environment-with-venv.md)
- [venv documentation](https://docs.python.org/3/library/venv.html)
- [What is a Virtual Environment?](https://pydevtools.com/handbook/explanation/what-is-a-virtual-environment.md)
- [Install packages in a virtual environment using pip and venv](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
- [Python Virtual Environments: A Primer](https://realpython.com/python-virtual-environments-a-primer/)