virtualenv

21.2.0 verified Fri Apr 10 auth: no python quickstart: verified

virtualenv is a tool for creating isolated Python environments, allowing developers to manage dependencies for different projects separately. The current version is 21.2.0, with regular updates to enhance functionality and maintain compatibility with Python versions.

pip install virtualenv

Common errors

error virtualenv: command not found ↓

cause The `virtualenv` command is not installed, or its executable location is not included in your system's PATH environment variable.

fix

Install virtualenv globally using pip: pip install virtualenv.

error failed to create virtual environment ↓

cause The virtual environment could not be created because the target directory does not exist or the user lacks write permissions for that location.

fix

Ensure the parent directory exists and you have write permissions, or specify a different path: mkdir my_project && cd my_project && virtualenv venv.

error Cannot find python interpreter ↓

cause `virtualenv` could not automatically locate a Python executable at common system paths.

fix

Specify the full path to your desired Python interpreter using the -p flag: virtualenv -p /usr/bin/python3.9 my_env.

error 'activate' is not recognized as an internal or external command, operable program or batch file. ↓

cause On Windows, the virtual environment activation script needs to be run by specifying its full path and correct file extension, typically from the `Scripts` directory.

fix

In Command Prompt, use: .\my_env\Scripts\activate.bat. In PowerShell, use: .\my_env\Scripts\Activate.ps1.

Warnings

breaking virtualenv 21.0.0 refactored the discovery module, which may affect custom scripts relying on internal APIs. ↓

fix Review and update custom scripts to align with the new discovery module structure.

deprecated The --relocatable option is experimental and may not work in all circumstances. ↓

fix Avoid using the --relocatable option; consider other methods for creating portable environments.

gotcha Creating a virtual environment without specifying the Python version may result in using an unintended interpreter. ↓

fix Use the -p option to specify the desired Python interpreter when creating a virtual environment.

gotcha System-wide PYTHONPATH settings can interfere with virtualenv's isolation. ↓

fix Ensure PYTHONPATH is unset or correctly configured when working within a virtual environment.

gotcha Moving a virtual environment directory can break its functionality due to absolute paths. ↓

fix Recreate the virtual environment in the new location instead of moving it.

gotcha Activation or deactivation of the virtual environment fails with 'sh: 1: source: not found' or 'sh: 1: deactivate: not found' errors, indicating that the shell's `source` command is not available or the activation script cannot be found in the current shell environment (e.g., when using a minimal shell like dash without sourcing capabilities). ↓

fix Ensure that the shell executing the activation command supports `source` (e.g., Bash, Zsh). If a minimal shell is used, consider explicitly calling the Python interpreter from the virtual environment's `bin` directory (e.g., `/path/to/venv/bin/python`) or ensure the `PATH` is correctly updated manually, or switch to a compatible shell for activation.

gotcha The 'deactivate' command was not found or could not be executed by the shell. This can occur if the virtual environment's activation script was not properly sourced, or if the 'deactivate' script is missing or corrupted. ↓

fix Ensure the virtual environment is correctly activated using 'source /path/to/venv/bin/activate'. If the issue persists, verify the integrity of the 'deactivate' script within the virtual environment's 'bin' directory or recreate the virtual environment.

Quickstart verified last tested: 2026-04-23

This script demonstrates how to create, activate, use, and deactivate a virtual environment using virtualenv.

import os

# Create a virtual environment
os.system('virtualenv myenv')

# Activate the virtual environment
if os.name == 'nt':
    os.system('.\\myenv\\Scripts\\activate')
else:
    os.system('source myenv/bin/activate')

# Install a package within the virtual environment
os.system('pip install requests')

# Deactivate the virtual environment
os.system('deactivate')