虚拟环境

约 2593 字大约 9 分钟

2025-05-02

虚拟环境

在同一台服务器或开发机中，我们经常需要同时运行多个 Python 项目。这些项目往往依赖于不同版本的第三方包。例如： - 项目 A 依赖 Django 1.11 - 项目 B 依赖 Django 2.0

虚拟环境的特征
生态工具概览
venv 模组使用指南
virtualenv

学习练习清单

1在项目目录跑 python -m venv .venv，再 source .venv/bin/activate，看终端前缀变了说明激活成功。
2激活后跑 which python 和 which pip，确认指向 .venv 里 —— 这就是 PATH 临时插队的原理。
3把 .venv/ 加进 .gitignore，永远不要把虚拟环境提交到仓库。
4对新项目试一次 uv init && uv add requests && uv run main.py，体会“无需手动激活”的现代工作流。
5需要装 numpy/pytorch 这类带二进制依赖的库且老遇到编译问题 —— 切到 Conda 通常能解决。

在同一台服务器或开发机中，我们经常需要同时运行多个 Python 项目。这些项目往往依赖于不同版本的第三方包。例如：

项目 A 依赖 Django 1.11
项目 B 依赖 Django 2.0

由于同一个 Python 解释器在全局环境中只能安装一个版本的库，后安装的版本会覆盖先安装的版本。这会导致不同项目之间产生依赖冲突（Dependency Hell），使得项目无法正常运行。

为了解决这个问题，我们需要将不同项目的依赖环境隔离开。标准做法是为每个项目创建一个独立的虚拟环境（Virtual Environment）。每个项目的第三方包都安装在自己的虚拟环境中，互不干扰。

虚拟环境的特征

Python 官网对虚拟环境的定义如下：

笔记

隔离性：包含特定版本的 Python 解释器、软件库和二进制文件。默认与其他虚拟环境及系统全局环境保持隔离。
目录结构：通常是项目根目录下的 .venv 或 venv 文件夹。
不可版本控制：切勿将虚拟环境目录提交到 Git 等版本控制系统。
一次性：被认为是可丢弃的。如果坏了，直接删除并重新创建即可。

有关 Python 虚拟环境的更多背景信息可查阅 PEP 405。

生态工具概览

Python 生态中有多种建立和管理虚拟环境的工具。除了基础的环境隔离，部分工具还集成了包管理、版本管理、打包发布等功能。

下图是各个工具的能力范围概括（注：图中未包含近期热门的 uv 等新工具）：

`venv` 模组使用指南

venv 是 Python 3.3+ 内置的标准虚拟环境管理模块，以轻量、零依赖著称，是 Python 官方推荐的基础工具。

创建虚拟环境

在项目根目录下，运行以下命令创建一个名为 .venv 的虚拟环境：

# macOS / Linux / Windows
python3 -m venv .venv

这会在当前目录生成一个 .venv 文件夹，其中包含了一份独立的 Python 解释器副本和 pip 工具。

激活虚拟环境

创建后需要激活才能使用。激活后，终端的命令提示符通常会显示虚拟环境的名称（如 (.venv)）。

macOS / Linux:
```
source .venv/bin/activate
```
Windows (CMD):
```
.venv\Scripts\activate.bat
```
Windows (PowerShell):
```
.venv\Scripts\Activate.ps1
```

提示

激活的原理其实是将虚拟环境的 bin (Linux/Mac) 或 Scripts (Windows) 目录临时添加到了系统的 PATH 环境变量的最前面。这样当你输入 python 或 pip 时，系统会优先使用虚拟环境中的版本。

管理依赖

激活环境后，你可以像平常一样使用 pip 安装包，它们会被安装到 .venv 目录中，而不会影响全局环境。

pip install requests

最佳实践：使用 requirements.txt 记录项目依赖。

导出依赖：
```
pip freeze > requirements.txt
```
安装依赖（在另一个环境或新机器上）：
```
pip install -r requirements.txt
```

退出虚拟环境

完成工作后，执行以下命令退出虚拟环境，恢复到系统全局环境：

deactivate

Git 版本控制设置

正如前文所述，不要将虚拟环境文件夹提交到 Git。请确保你的 .gitignore 文件中包含以下内容：

# .gitignore
.venv/
venv/
ENV/

`virtualenv`

virtualenv 是第三方包，可以视为 venv 的前身和加强版。在 Python 3.3 之前，它是创建虚拟环境的主要方式。即便现在有了内置的 venv，virtualenv 依然因其速度快、支持指定任意 Python 版本等特性而保有一席之地。

安装

pip install virtualenv

使用

创建环境（指定目录名，如 venv）：
```
virtualenv venv
```
如果想指定特定的 Python 解释器版本（这是 venv 做不到的）：
```
virtualenv -p python3.8 venv
```

激活与退出：操作方式与 venv 完全一致：

# 激活 (Linux/macOS)
source venv/bin/activate

# 退出
deactivate

`virtualenvwrapper`

virtualenv 和 venv 默认将环境创建在项目目录下。如果你管理着几十个项目，这些分散的环境可能难以维护。virtualenvwrapper 解决了这个问题，它将所有的虚拟环境统一存放在一个目录下（如 ~/.virtualenvs），并提供了一组便捷的 Shell 命令。

安装

Linux / macOS:
```
pip install virtualenvwrapper
```
Windows: 需安装 virtualenvwrapper-win：
```
pip install virtualenvwrapper-win
```

配置 (Linux / macOS)

安装后需要配置 shell 初始化文件（如 .bashrc 或 .zshrc）：

# 设置虚拟环境存放目录
export WORKON_HOME=$HOME/.virtualenvs

# 指定 Python3 路径 (可选)
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3

# 激活 virtualenvwrapper.sh (通常在 /usr/local/bin 或 pip 安装位置)
source /usr/local/bin/virtualenvwrapper.sh

注：virtualenvwrapper.sh 的实际路径可用 which virtualenvwrapper.sh 查找。

常用命令

配置生效后，可以使用简短的命令来高效管理环境：

创建环境（自动激活）：
```
mkvirtualenv my_project
```
列出所有环境：
```
workon
```
切换/激活环境：
```
workon my_project
```
删除环境：
```
rmvirtualenv my_project
```
退出环境：
```
deactivate
```

`Conda`

Conda 是一个开源的软件包管理系统和环境管理系统。与上述工具不同，它起初是为 Python 数据科学而设计，但也不局限于 Python。它最大的优势在于能处理复杂的二进制依赖。

特点

跨语言支持：不仅能管 Python 包，还能管 C/C++ 库（如 numpy 的底层依赖）。
自带 Python 解释器：每个环境都是完全独立的，不依赖系统 Python，甚至可以轻松安装不同版本的 Python。
二进制分发：安装预编译的包，无需本地编译，尤其适合安装科学计算类库。

常用命令

创建环境：
```
conda create -n my_env python=3.9
```
激活环境：
```
conda activate my_env
```
安装包：
```
conda install numpy pandas
```
退出环境：
```
conda deactivate
```

`uv` (现代之选)

uv 是一个由 Rust 编写的极速 Python 包和项目管理工具（由 Ruff 团队开发）。它旨在替代 pip、pip-tools 甚至 pipenv/poetry，提供统一且高性能的体验。它代表了 Python 工具链的未来方向。

特点

极速：得益于 Rust，速度比 pip 快 10-100 倍。
统一化：集成了 Python 版本管理、虚拟环境管理、包解析和安装。
现代化：默认使用标准 pyproject.toml 管理依赖，推崇声明式配置。

现代化工作流

uv 推荐使用基于项目的管理方式，而非传统的手动管理虚拟环境。

初始化项目：

# 初始化当前目录，创建 pyproject.toml
uv init

或者指定 Python 版本初始化：

uv init --python 3.12

添加依赖：不再手动编辑 requirements.txt 或运行 pip install，而是：
```
# 安装 requests 并自动写入 pyproject.toml 和 uv.lock
uv add requests
```
这会自动创建虚拟环境（默认在 .venv），安装包，并更新锁定文件。
同步环境：确保环境与 uv.lock 描述的一致：
```
uv sync
```
运行命令：在虚拟环境中运行脚本，无需显式激活：
```
uv run main.py
```
切换 Python 版本：如果想让项目使用不同的 Python 版本：
```
uv python pin 3.11
uv sync
```

总结与对比

面对如此多的工具，如何选择最适合你的那一个？以下是详细对比与建议：

工具	来源	管理方式	解释器版本管理*	特点	适用场景
`venv`	内置 (Python 3.3+)	项目目录下 (`.venv`)	❌ (依赖系统当前解释器)	轻量、标准库自带	简单的脚本、学习、无需管理 python 版本
`virtualenv`	第三方	项目目录下	✅ (需已安装对应解释器)	速度快、功能丰富	需要支持旧版 Python、需要更多配置选项
`virtualenvwrapper`	第三方扩展	统一目录 (`~/.virtualenvs`)	✅	便捷的切换和管理命令	需要频繁切换多个环境、偏好集中管理
`Conda`	Anaconda Inc.	统一目录	✅ (支持直接安装新解释器)	强大的二进制包管理、支持C库	数据科学、机器学习、依赖复杂的环境
`uv`	Astral (Rust)	项目目录下 (默认)	✅ (支持自动下载/安装 Python)	极速、All-in-One、现代化工作流	现代 Python 开发首选、大型项目

注："解释器版本管理" 指工具是否方便指定或安装不同版本的 Python。如 venv 只能基于运行该命令的解释器创建环境，而 uv 和 Conda 可以为你下载和安装特定版本的 Python。

选型建议

新手入门 / 快速脚本：直接用 venv，系统自带最省事。
数据科学 / AI 开发：首选 Conda (或 Miniconda)，解决环境依赖最强。
现代 Web / 应用开发：强烈推荐 uv。速度极快，且统一了包管理和环境管理，是未来的趋势。

要点回收

虚拟环境本质是“给项目一份独立的 Python 解释器副本 + site-packages”，靠 PATH 切换实现隔离。
venv 是 3.3+ 内置的官方方案，零依赖；virtualenv 更快、能指定任意 Python 版本。
环境目录永远不进版本控制；要重建只需 .venv/ 删掉重跑 python -m venv 即可。
数据科学/二进制依赖复杂选 Conda；现代 Web/应用项目首选 uv —— 集环境、依赖、Python 版本于一身。
无论用哪种工具，激活后 which python/pip 都指向虚拟环境，这是“激活成功”的真正信号。

版权所有

版权归属：Shuo Liu

许可证：署名-非商业性 4.0 国际 (CC-BY-NC-4.0)