Python venv: How to Create and Use Virtual Environments

A Python virtual environment is a self-contained directory that includes its own Python interpreter and a set of installed packages, isolated from the system-wide Python installation. Using virtual environments lets each project maintain its own dependencies without affecting other projects on the same machine.

This guide explains how to create and manage virtual environments using venv (built into Python 3) and virtualenv (a popular third-party alternative) on Linux and macOS.

Quick Reference #

What Is a Python Virtual Environment? #

When you install a package globally with pip install, it is available to every Python script on the system. This becomes a problem when two projects need different versions of the same library. For example, one project requires requests==2.28.0 and another requires requests==2.31.0. Installing both globally is not possible.

A virtual environment solves this by giving each project its own isolated space for packages. Activating an environment prepends its bin/ directory to your PATH, so python and pip resolve to the versions inside the environment rather than the system-wide ones.

Installing venv #

The venv module ships with Python 3 and requires no separate installation on most systems. On Ubuntu and Debian, the module is packaged separately:

sudo apt install python3-venv

On Fedora, RHEL, and Derivatives, venv is included with the Python package by default.

Verify your Python version before creating an environment:

python3 --version

For more on checking your Python installation, see How to Check Python Version .

Creating a Virtual Environment #

Navigate to your project directory and run:

python3 -m venv venv

The second venv is the name of the directory that will be created. The conventional names are venv or .venv. The directory contains a Python binary or symlink, activation scripts, pip, and a site-packages directory for installed packages.

To create the environment in a specific location rather than the current directory:

python3 -m venv ~/projects/myproject/venv

Useful venv Flags #

python3 -m venv accepts a few flags worth knowing:

• --system-site-packages lets the environment see packages installed in the system Python. Useful when a heavy dependency is easier to install via the system package manager.
• --without-pip skips the bundled pip. You can install pip later with python -m ensurepip.
• --copies copies the Python binary into the environment instead of symlinking it. The default uses symlinks, which is faster but ties the environment to the original interpreter path.
• --upgrade-deps upgrades the core venv dependencies, such as pip, to the latest versions on PyPI right after creation.
• --upgrade rebuilds the environment against a new Python version when the system Python is upgraded. Run python3 -m venv --upgrade /path/to/existing/venv.

A common combined form when starting a new project:

python3 -m venv --upgrade-deps myenv

Activating the Virtual Environment #

Before using the environment, you need to activate it.

On Linux and macOS:

source venv/bin/activate

If you use fish or csh, source the matching script in the same bin/ directory: activate.fish or activate.csh. On Windows, the activation script lives at venv\Scripts\activate for cmd or venv\Scripts\Activate.ps1 for PowerShell.

Once activated, your shell prompt changes to show the environment name:

(venv) user@host:~/myproject$

From this point on, python and pip refer to the versions inside the virtual environment, not the system-wide ones.

To deactivate the environment and return to the system Python:

deactivate

The pyvenv.cfg File #

Each environment contains a pyvenv.cfg file at its root. It records the interpreter the environment was built from, the Python version, and a flag controlling system site packages:

home = /usr/bin
include-system-site-packages = false
version = 3.12.3

If you need to flip access to system packages without recreating the environment, edit include-system-site-packages to true. The other settings should not be edited by hand, since they are regenerated when the environment is rebuilt.

Installing Packages #

With the environment active, install packages using pip as you normally would. If pip is not installed on your system, see How to Install Python Pip on Ubuntu .

pip install requests

To install a specific version:

pip install requests==2.31.0

To list all packages installed in the current environment:

pip list

Packages installed here are completely isolated from the system and from other virtual environments.

Managing Dependencies with requirements.txt #

Sharing a project with others, or deploying it to another machine, requires a way to reproduce the same package versions. The convention is to save all dependencies to a requirements.txt file:

pip freeze > requirements.txt

The file lists every installed package and its exact version:

certifi==2024.2.2
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.2.1

To install all packages from the file in a fresh environment:

pip install -r requirements.txt

This is the standard workflow for reproducing an environment on a different machine or in a CI/CD pipeline.

Using a Specific Python Version #

By default, python3 -m venv uses whichever Python 3 version is the system default. If you have multiple Python versions installed, you can specify which one to use:

python3.11 -m venv venv

This creates an environment based on Python 3.11 regardless of the system default. To check which versions are available :

python3 --version
python3.11 --version

virtualenv: An Alternative to venv #

virtualenv is a third-party package that predates venv and offers a few additional features. Install it with pip:

pip install virtualenv

Creating and activating an environment with virtualenv follows the same pattern:

virtualenv venv
source venv/bin/activate

To use a specific Python interpreter:

virtualenv -p python3.11 venv

When to use virtualenv over venv:

• You need to create environments faster. virtualenv is noticeably faster on large projects.
• You are working with Python 2 (legacy codebases only).
• You need features like --copies to copy binaries instead of symlinking.

For most modern Python 3 projects, venv is sufficient and has the advantage of requiring no installation.

uv: A Faster Modern Alternative #

uv is a newer Python package manager written in Rust that includes a built-in venv command. It is significantly faster than both venv and virtualenv for environment creation and package installation. To create an environment with uv:

uv venv myenv
source myenv/bin/activate

uv is becoming a common pick when install speed matters in CI, but venv remains the right default when you want zero extra dependencies.

Installing Tools with pipx #

Sometimes you want a Python tool installed globally so it is always available, but without polluting the system Python or creating a per-project venv. pipx solves this by giving each tool its own private virtual environment that you never need to activate.

Install pipx and use it for a CLI tool like httpie:

sudo apt install pipx
pipx install httpie

Use venv for project dependencies and pipx for command-line tools. The two solve different problems.

Excluding the Environment from Version Control #

The virtual environment directory should never be committed to version control. It is large, machine-specific, and fully reproducible from requirements.txt. Add it to your .gitignore:

echo "venv/" >> .gitignore

If you named your environment .venv instead, add .venv/ to .gitignore.

Troubleshooting #

python3 -m venv venv fails with “No module named venv”
On Ubuntu and Debian, the venv module is not included in the base Python package. Install it with sudo apt install python3-venv, then retry.

pip install installs packages globally instead of into the environment
The environment is not activated. Run source venv/bin/activate first. You can verify by checking which pip, which should point to a path inside your venv/ directory.

python still points outside the environment after activation
The environment may not be activated, or your shell may be caching an older command path. Run source venv/bin/activate, then check which python and which pip. In Bash or Zsh, run hash -r if the shell still resolves an old path.

The environment breaks after moving or renaming its directory
Virtual environments contain hardcoded absolute paths to the Python interpreter. Moving or renaming the directory invalidates those paths. Delete the directory and recreate the environment in the new location, then reinstall from requirements.txt.

FAQ #

What is the difference between venv and virtualenv?
venv is a standard library module included with Python 3, so no installation is needed. virtualenv is a third-party package with a longer history, faster environment creation, and Python 2 support. For new Python 3 projects, venv is the recommended choice.

Should I commit the virtual environment to git?
No. Add venv/ (or .venv/) to your .gitignore and commit only requirements.txt. Anyone checking out the project can recreate the environment with pip install -r requirements.txt.

Do I need a virtual environment for every project?
It is strongly recommended. Without isolated environments, installing or upgrading a package for one project can break another. The overhead of creating a virtual environment is minimal.

What is the difference between pip freeze and pip list?
pip list shows installed packages in a human-readable format. pip freeze outputs them in requirements.txt format (package==version) suitable for use with pip install -r.

Can I use a virtual environment with a different Python version than the system default?
Yes. Pass the path to the desired interpreter when creating the environment: python3.11 -m venv venv. The environment will use that interpreter for both python and pip commands.

Should I use venv or pipx for CLI tools like black, ruff, or httpie?
Use pipx. It gives each tool its own private environment so installs do not collide, and you never need to activate anything to run the tool. Reserve venv for the libraries your project imports.

What does pyvenv.cfg do?
It is a small config file written at the root of every venv. It records which interpreter the environment was built from, the Python version, and whether the environment can see system site packages. The include-system-site-packages flag is the only line you usually edit by hand.

Conclusion #

Virtual environments are the standard way to manage Python project dependencies. Create one with python3 -m venv venv, activate it with source venv/bin/activate, and use pip freeze > requirements.txt to capture your dependencies. For more on managing Python installations, see How to Check Python Version .

About the authors

Dejan Panovski

Dejan Panovski is the founder of Linuxize, an RHCSA-certified Linux system administrator and DevOps engineer based in Skopje, Macedonia. Author of 800+ Linux tutorials with 20+ years of experience turning complex Linux tasks into clear, reliable guides.

View author page