`venv`

The Python venv module provides support for creating isolated Python virtual environments. This allows you to manage dependencies for different projects separately, preventing conflicts and ensuring that each project has access to the packages it needs.

Here’s a quick example:

>>> import venv

>>> builder = venv.EnvBuilder(with_pip=True)
>>> builder.create("/path/to/virtual/environment")

This module is commonly used from the command line to create virtual environments:

$ python -m venv .venv/

Key Features

Creates isolated Python environments
Installs pip in new environments for package management
Allows customization of the virtual environment creation process
Enables quick activation and deactivation of environments
Supports cross-platform environment creation
Writes a .gitignore file into new environments by default so Git ignores them (since Python 3.13)
Provides a standard, built-in solution for dependency management
Prevents conflicts between project dependencies

Frequently Used Commands and Options

Command / Option	Description
`python -m venv ./venv`	Creates a new virtual environment in the `./venv` directory
`python -m venv --system-site-packages ./venv`	Gives the environment access to system-wide packages
`python -m venv --clear ./venv`	Clears the environment directory if it already exists
`python -m venv --upgrade ./venv`	Upgrades the environment directory to use the current Python version (use after upgrading Python in-place)
`python -m venv --upgrade-deps ./venv`	Upgrades the environment’s core dependencies (`pip`) to the latest versions on PyPI
`python -m venv --without-scm-ignore-files ./venv`	Skips writing the source-control ignore files that `venv` creates by default, such as `.gitignore`
`source venv/bin/activate` (macOS/Linux) `.\venv\Scripts\activate` (Windows)	Activates the environment
`deactivate`	Deactivates the current virtual environment

Frequently Used Classes and Functions

Object	Type	Description
`venv.EnvBuilder`	Class	Builds and manages virtual environments
`venv.EnvBuilder.create()`	Method	Creates a virtual environment at the specified path using the builder’s configuration
`venv.create()`	Function	Creates a virtual environment at the specified path
`venv.EnvBuilder.post_setup()`	Method	Hook for custom post-creation steps, such as pre-installing packages into the new environment

Examples

Using EnvBuilder to customize environment creation:

>>> import venv

>>> builder = venv.EnvBuilder(with_pip=True, clear=True)
>>> builder.create("/path/to/virtual/environment")

Common Use Cases

Creating isolated environments for Python projects
Managing dependencies separately for each project
Setting up a clean Python environment for testing and development
Reproducing consistent environments for collaboration and deployment
Testing packages in fresh environments before release
Avoiding dependency conflicts in multi-project workflows

Real-World Example

Imagine you’re a DevOps engineer who needs to automate the setup of project directories, each with its own isolated Python environment. You can use the venv module programmatically to create and configure virtual environments as part of your provisioning scripts:

>>> import pathlib
>>> import venv

>>> def create_project_venv(project_name: str) -> pathlib.Path:
...     project_dir = pathlib.Path(project_name)
...     env_dir = project_dir / ".venv"
...     venv.create(env_dir, with_pip=True)
...     return env_dir
...

>>> env_path = create_project_venv("project")
>>> env_path.exists()
True

This function automates the creation of a project directory and its virtual environment. You can now easily set up isolated Python environments for any project by passing the desired directory name to the function.