Virtualenv — Isolated Python Environments for Every Project

Introduction

Virtualenv is a tool for creating isolated Python environments. Each environment gets its own Python binary and site-packages directory, allowing different projects to use different package versions without interference. It is the foundational isolation tool that predates and inspired Python's built-in venv module.

What Virtualenv Does

• Creates self-contained Python environments with isolated package directories
• Supports creating environments for different Python interpreter versions
• Provides activation scripts for bash, zsh, fish, PowerShell, and cmd.exe
• Installs pip and setuptools into each environment automatically
• Works on Linux, macOS, and Windows with consistent behavior

Architecture Overview

Virtualenv creates a new directory structure containing a copy or symlink of the Python interpreter, a fresh site-packages directory, and shell activation scripts. When activated, the environment prepends its bin directory to PATH so that python and pip resolve to the environment's copies. Package installations go into the environment's site-packages, completely isolated from the system Python.

Self-Hosting & Configuration

• Install via pip: pip install virtualenv or use pipx: pipx install virtualenv
• Create an environment: virtualenv myenv (uses the current Python by default)
• Specify a Python version: virtualenv -p python3.11 myenv
• Activate on Unix: source myenv/bin/activate; on Windows: myenvScriptsactivate
• Configure defaults in virtualenv.ini or via environment variables like VIRTUALENV_PYTHON

Key Features

• Faster environment creation than the built-in venv module with seed package caching
• Support for creating environments with Python versions different from the system default
• Extensible via plugins for custom app-data directories and seed mechanisms
• Discovery mechanism to locate Python interpreters across the system
• Built-in support for creating environments without pip using --no-pip for minimal setups

Comparison with Similar Tools

• venv (stdlib) — Built into Python 3.3+; virtualenv is faster, more configurable, and supports more Python versions
• conda — Full package and environment manager for multiple languages; virtualenv is Python-only and pip-based
• Poetry — Dependency manager that creates virtualenvs internally; virtualenv is the standalone environment tool
• pipenv — Combines Pipfile dependency management with virtualenv; virtualenv handles isolation only
• uv — Ultra-fast Rust-based Python installer that includes virtualenv creation; virtualenv is the established pure-Python tool

FAQ

Q: Should I use virtualenv or the built-in venv module? A: Virtualenv is faster, supports more Python versions, and has richer configuration. Use venv when you need zero external dependencies and basic isolation is sufficient.

Q: Can I create environments for Python versions not installed system-wide? A: Virtualenv discovers available Python interpreters but cannot install new ones. Use pyenv or similar tools to install additional Python versions first.

Q: How do I delete a virtual environment? A: Deactivate it with deactivate, then delete the directory: rm -rf myenv.

Q: Does virtualenv work with Python 2? A: Virtualenv version 20+ requires Python 3.7+ to run but can create environments for Python 2.7 if the interpreter is available on the system.

Sources

• https://github.com/pypa/virtualenv
• https://virtualenv.pypa.io/