Python Virtual Environment (venv)

A virtual environment is an isolated Python runtime space with its own interpreter, installed packages, and configuration, completely isolated from the system global environment.

Python Virtual Environment is an independent Python runtime environment that allows you to create isolated Python environments for different projects on the same machine.

Different projects can run in parallel in their respective virtual environments without interfering with each other.

Each virtual environment has its own:

• Python interpreter
• Installed packages/libraries
• Environment variables

Virtual environments give each project an independent dependency space, completely eliminating version conflicts

Why Virtual Environments Are Needed

• Project Isolation: Different projects can use different versions of Python and third-party libraries
• Avoid Pollution: Installed packages only affect the current environment, not polluting the global Python
• Controllable Dependencies: Accurately record and reproduce the environment through requirements.txt
• Safe Testing: You can safely upgrade or try out new packages without affecting other projects

Scenario Example:

• Project A requires Django 3.2
• Project B requires Django 4.0
• If installed globally, the two versions will conflict

Virtual Environment Tools

Tool Name	Type	Python Version Support	Installation Method	Features	Use Cases
venv (Recommended)	Built-in Module	≥ 3.3	No installation required, built-in	Lightweight, officially recommended, simple to use	General development, daily projects
virtualenv	Third-party Tool	2.x and 3.x	pip install virtualenv	Rich features, multi-version compatibility	Projects needing legacy version or advanced features
conda	Anaconda Built-in	2.x and 3.x	Installed with Anaconda/Miniconda	Cross-language package management, data science ecosystem	Data science, machine learning projects

If older version support is needed, you can use virtualenv (Python 2 compatible):

pip install virtualenv  # Not required, venv is usually sufficient

This chapter will use venv to create and manage virtual environments.

---

Creating a Virtual Environment

Python 3.3+ has the venv module built-in, requiring no additional installation.

Usage Process

Usage Process Overview

1 Create python -m venv 2 Activate activate 3 Install Dependencies pip install 4 Develop/Debug python / run 5 Deactivate deactivate

Check the Python version:

python3 --version
# or
python --version

Create a virtual environment:

# Basic syntax
python3 -m venv environment_name

For example, create a virtual environment named .venv:

Example

# Enter the project directory
mkdir my_project && cd my_project

# Create a virtual environment (naming it '.venv' is a common convention)
python3 -m venv .venv

Parameter Description:

• -m venv: Use the venv module
• .venv: The name of the virtual environment (can be customized)

Directory Structure After Creation

.venv/
├── bin/            # On Unix/Linux systems
│   ├── activate    # Activation script
│   ├── python      # Environment Python interpreter
│   └── pip         # Environment's pip
├── Scripts/        # On Windows systems
│   ├── activate    # Activation script
│   ├── python.exe  # Environment Python interpreter
│   └── pip.exe     # Environment's pip
└── Lib/            # Installed third-party libraries

---

Activating the Virtual Environment

After activation, the python and pip commands in the current terminal will automatically point to the virtual environment, and all installation operations will be performed in the isolated space.

macOS / Linux

source .venv/bin/activate

Windows (CMD / PowerShell)

.venv\Scripts\activate

After successful activation, the command prompt usually displays the environment name:

(.venv) $

Verify that activation is in effect:

# Check the Python path, it should point to the .venv directory
which python       # macOS/Linux
where python       # Windows
→ /path/to/my_project/.venv/bin/python

---

Using the Virtual Environment

Installing Packages

In an activated environment, packages installed using pip will only affect the current environment:

pip install package_name

For example:

# Install a single package (e.g., Django)
(.venv) pip install django==3.2.12

# Install multiple packages
(.venv) pip install requests pandas

# Slow installation? Use a domestic mirror
(.venv)  pip install django -i https://pypi.tuna.tsinghua.edu.cn/simple

Viewing Installed Packages

(.venv) pip list
Package    Version
---------- -------
Django     3.2.12
pip        21.2.4

# View details of a specific package
(.venv) pip show django

# Upgrade a package
(.venv) pip install --upgrade pip

Exporting Dependencies

Using requirements.txt to record and reproduce the project environment is a standard practice for team collaboration:

(.venv) pip freeze > requirements.txt

Example content of requirements.txt file:

Django==3.2.12
requests==2.26.0
pandas==1.3.3

Installing Dependencies from a File

(.venv) pip install -r requirements.txt

Tip: Add .venv/ to .gitignore and only commit requirements.txt. Virtual environments are large in size and path-bound, so they should not be included in version control.

---

Exiting the Virtual Environment

When you finish working, you can exit the virtual environment:

deactivate

After exiting, the command prompt will return to normal, and Python and pip commands will use the system global version.

---

Deleting the Virtual Environment

To delete a virtual environment, simply delete the corresponding directory:

# Ensure you have exited the environment
deactivate

Deleting the Virtual Environment

A virtual environment is essentially a regular directory. Deleting the directory completely removes it:

macOS / Linux

rm -rf .venv

Windows

rmdir /s /q .venv

Note: Before deleting, execute deactivate to exit the environment first; otherwise, the current Shell will retain invalid environment variables.

---

Real Project Example

Suppose you are developing a Django project:

Example

# 1. Create and enter the project directory
mkdir my_site && cd my_site

# 2. Create a virtual environment and activate it
python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

# 3. Install Django and record dependencies
(.venv) pip install django==4.2
(.venv) pip freeze > requirements.txt

# 4. Initialize the Django project
(.venv) django-admin startproject config .

# 5. Database migration and start the development server
(.venv) python manage.py migrate
(.venv) python manage.py runserver

# 6. Development complete, exit the environment
(.venv) deactivate

---

Advanced Usage

Specifying Python Version

If you have multiple Python versions installed, you can specify which version to use to create the virtual environment:

python3.8 -m venv .venv  # Use Python 3.8

Creating an Environment Without pip

python -m venv --without-pip .venv

Creating a Virtual Environment That Inherits System Packages

python -m venv --system-site-packages .venv

---

Frequently Asked Questions

1. Why doesn’t my virtual environment have an activate script?

Make sure you are using the correct path:

• Windows: Scripts\activate
• Unix/Linux: bin/activate

2. How do I know if I’m currently in a virtual environment?

Check if the command prompt has an environment name prefix, or run:

which python

3. Slow package installation

Use a domestic mirror source:

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name

Check if the Python interpreter’s path is in the virtual environment directory.

4. Can the virtual environment be moved?

Not recommended. Scripts and configuration files within the virtual environment contain hardcoded absolute paths, which will become invalid after moving. If migration is needed, the easiest way is to recreate the environment and restore dependencies through requirements.txt.

5. How much space does a virtual environment take?

An empty environment is about 20–50 MB, increasing as more packages are installed. Data science projects (NumPy, Pandas, PyTorch) can reach several GB. Regularly cleaning up unused virtual environments is a good habit.

---

Best Practices

1. One environment per project: Avoid dependencies from different projects interfering with each other
2. Unified naming as .venv: Most IDEs (VS Code, PyCharm) can automatically recognize it
3. Update requirements.txt promptly: Sync and export after each pip install
4. Ignore virtual environments in version control: Add .venv/ to .gitignore
5. Regularly clean up abandoned environments: Free up disk space
6. Pin version numbers in production: Explicitly write == versions in requirements.txt to avoid accidental upgrades

# .gitignore recommended configuration
.venv/
__pycache__/
*.pyc
.env
*.egg-info/