Python venv: Complete Virtual Environment Guide (2026)

Virtual environments are one of the first things every Python developer needs to learn. They isolate project dependencies so that installing packages for one project does not break another. Python's built-in venv module is the standard way to create them, and this guide covers everything from the basics to advanced workflows.

Why Use Virtual Environments?

Without virtual environments, all Python packages install globally. This causes problems:

# Project A needs Django 4.2
pip install django==4.2

# Project B needs Django 5.1
pip install django==5.1
# This overwrites Django 4.2 -- Project A is now broken

Virtual environments solve this by giving each project its own isolated set of packages:

project-a/
  .venv/       # Contains Django 4.2
  manage.py

project-b/
  .venv/       # Contains Django 5.1
  manage.py

Each .venv directory contains its own Python interpreter and packages, completely independent from each other.

Creating a Virtual Environment

Basic Usage

# Navigate to your project directory
cd /path/to/your/project

# Create a virtual environment named .venv
python3 -m venv .venv

The convention is to name the directory .venv (with a leading dot so it is hidden). Some teams use venv, env, or .env, but .venv is the most widely adopted standard.

Specifying a Python Version

# Use a specific Python version
python3.12 -m venv .venv

# Or on systems with multiple versions
/usr/local/bin/python3.13 -m venv .venv

The virtual environment uses whichever Python binary you invoke it with.

What Gets Created

.venv/
  bin/              # Scripts (activate, pip, python) -- Linux/macOS
  Scripts/          # Scripts (activate, pip, python) -- Windows
  lib/
    python3.12/
      site-packages/  # Installed packages go here
  include/          # C header files for compiling extensions
  pyvenv.cfg        # Configuration file

Activating the Virtual Environment

macOS / Linux

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1

Windows (Command Prompt)

.venv\Scripts\activate.bat

Fish Shell

source .venv/bin/activate.fish

When activated, your terminal prompt changes to show the environment name:

(.venv) user@machine:~/project$

Verifying Activation

# Check that python points to the venv
which python
# Output: /path/to/project/.venv/bin/python

# Check pip points to the venv
which pip
# Output: /path/to/project/.venv/bin/pip

# Confirm the Python path
python -c "import sys; print(sys.prefix)"
# Output: /path/to/project/.venv

Installing Packages

With the virtual environment activated, pip install installs packages only into the venv:

# Install a single package
pip install requests

# Install a specific version
pip install django==5.1.2

# Install multiple packages
pip install flask sqlalchemy celery

# Install from requirements file
pip install -r requirements.txt

Creating requirements.txt

# Freeze current packages to requirements.txt
pip freeze > requirements.txt

This generates a file like:

certifi==2024.12.14
charset-normalizer==3.4.1
django==5.1.2
idna==3.10
requests==2.32.3
sqlparse==0.5.3
urllib3==2.3.0

Using requirements.txt

# Install all dependencies from requirements file
pip install -r requirements.txt

This is how team members reproduce your exact environment.

Deactivating the Virtual Environment

deactivate

Your prompt returns to normal, and python and pip point back to the system-wide installation.

Virtual Environment Best Practices

1. Always Add .venv to .gitignore

Virtual environments should never be committed to version control:

# .gitignore
.venv/
venv/
env/
__pycache__/
*.pyc

Commit requirements.txt (or pyproject.toml) instead. Team members recreate the venv from the requirements file.

2. Use pyproject.toml for Modern Projects

For new projects in 2026, pyproject.toml is preferred over requirements.txt:

[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = [
    "django>=5.1",
    "requests>=2.32",
    "celery>=5.4",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.8",
    "mypy>=1.13",
]

Install with:

pip install -e .           # Install project + dependencies
pip install -e ".[dev]"    # Include dev dependencies

3. Pin Dependency Versions for Production

Use pip freeze or a lock file for production deployments:

# Generate a fully pinned lock file
pip freeze > requirements-lock.txt

# For development, keep loose versions
# requirements.txt
django>=5.1,<6.0
requests>=2.32

4. One Virtual Environment per Project

Never share a virtual environment between projects:

# Good: Each project has its own venv
project-a/.venv/
project-b/.venv/

# Bad: Shared venv
shared-env/  # Used by both projects -- will cause conflicts

5. IDE Integration

VS Code / Cursor

VS Code and Cursor auto-detect .venv in your project root. If not:

Open Command Palette (Cmd+Shift+P)
Type: Python: Select Interpreter
Choose the interpreter from .venv/bin/python

Or add to .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

PyCharm

PyCharm detects virtual environments automatically. To configure manually:

Go to Settings > Project > Python Interpreter
Click the gear icon > Add
Select Existing Environment
Browse to .venv/bin/python

Common Tasks

Upgrading pip Inside the venv

python -m pip install --upgrade pip

Listing Installed Packages

pip list

# Show only packages you installed (not dependencies)
pip list --not-required

Checking for Outdated Packages

pip list --outdated

Removing a Package

pip uninstall requests

Recreating a Virtual Environment

If your venv gets corrupted or you want a fresh start:

# Delete the old venv
rm -rf .venv

# Create a new one
python3 -m venv .venv

# Activate and reinstall
source .venv/bin/activate
pip install -r requirements.txt

venv vs. Other Tools

Tool	Built-in	Lock File	Multiple Python Versions	Speed	Best For
venv	Yes	No (use pip freeze)	No (manual)	Fast	Simple projects
uv	No (pip install)	Yes	Yes	Fastest	Modern Python dev
Poetry	No (pip install)	Yes	No	Medium	Library authors
Conda	No (separate install)	Yes	Yes	Slow	Data science
pipenv	No (pip install)	Yes	No	Slow	Legacy projects
hatch	No (pip install)	Yes	Yes	Fast	PEP-compliant projects

When to Use venv

Use venv when:

You want zero extra dependencies (it is built into Python)
Your project is straightforward with a simple dependency tree
You are learning Python and want to understand the basics
Your team already uses requirements.txt

When to Use uv Instead

In 2026, uv has become the most popular alternative. It is a drop-in replacement that is dramatically faster:

# Install uv
pip install uv

# Create a venv (10x faster than venv)
uv venv

# Install packages (100x faster than pip)
uv pip install -r requirements.txt

# Sync dependencies with lock file
uv sync

If speed matters and you do not mind an extra tool, uv is the modern choice.

Troubleshooting Common Issues

"python3 -m venv" Returns an Error

On Ubuntu/Debian:

# Install the venv module (not included by default)
sudo apt install python3-venv

On Fedora/RHEL:

sudo dnf install python3-venv

Activation Script Not Found

# Check if the venv was created properly
ls .venv/bin/activate

# If missing, recreate the venv
rm -rf .venv
python3 -m venv .venv

"Permission denied" on Windows

Run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Packages Installing Globally Despite Active venv

Check that activation actually worked:

echo $VIRTUAL_ENV
# Should output: /path/to/project/.venv

# If empty, activation failed -- try again
source .venv/bin/activate

Python Version Mismatch After OS Update

After a Python update, your venv might reference an old interpreter:

# Check the venv Python version
.venv/bin/python --version

# If it errors or shows wrong version, recreate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Quick Reference

Command	Description
`python3 -m venv .venv`	Create a virtual environment
`source .venv/bin/activate`	Activate (macOS/Linux)
`.venv\Scripts\activate`	Activate (Windows)
`deactivate`	Deactivate
`pip install package`	Install a package
`pip freeze > requirements.txt`	Export dependencies
`pip install -r requirements.txt`	Install from file
`pip list`	List installed packages
`pip list --outdated`	Check for updates
`rm -rf .venv`	Delete the venv

Wrapping Up

Python's venv module is simple, reliable, and built into the language. For most projects, it is all you need to manage isolated dependencies. Start every new project by creating a .venv, add it to .gitignore, and commit your requirements.txt or pyproject.toml so your team can reproduce the environment.

If you are building Python applications that involve AI-generated media, Hypereal AI offers Python-friendly APIs for image generation, video creation, lip sync, and talking avatars. Sign up free to explore the API.