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:

Python
>>> 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:

Shell
$ 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
  • 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 with the latest Python executable
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.main() Function Runs the command-line interface (CLI) for virtual environment creation

Examples

Using EnvBuilder to customize environment creation:

Python
>>> 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:

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

Tutorial

Python Virtual Environments: A Primer

In this tutorial, you'll learn how to use a Python virtual environment to manage your Python projects. You'll also gain a deep understanding of the structure of virtual environments created with the venv module, as well as the rationale behind using virtual environments.

intermediate devops tools

For additional information on related topics, take a look at the following resources:


By Leodanis Pozo Ramos • Updated July 29, 2025