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

## 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 new work where third-party tools are available, [uv](https://pydevtools.com/handbook/reference/uv.md) creates and manages virtual environments automatically through `uv run` and `uv sync`, removing the manual create-and-activate steps venv requires.

> [!NOTE]
> For new projects, [uv](https://pydevtools.com/handbook/reference/uv.md) is the recommended alternative. It creates virtual environments automatically, installs packages faster, and handles Python version management — eliminating most of the manual steps described on this page. venv remains useful for understanding how virtual environments work under the hood and for environments where installing third-party tools is not an option.

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

- [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/)