Python虚拟环境(venv)的全面使用指南_Python

摘要

python 虚拟环境（virtual environment）是 python 开发中不可或缺的隔离机制。它允许你在同一台机器上为不同项目创建独立的隔离的 python 运行环境，每个环境拥有自己的解释器、第三方库和配置文件，彻底有效解决了**依赖地狱(依赖冲突)**问题。本指南基于官方 venv 模块，结合跨平台实战经验，从背景历史到进阶技巧，全方位解析虚拟环境的创建、管理、依赖处理及避坑指南。

一、背景、发展历史与方向

1. 为什么需要虚拟环境？

在 python 开发中，不同项目往往依赖不同版本的库：

项目 a：需要 django 3.2
项目 b：需要 django 4.0
全局环境：只能安装一个版本，导致冲突。

虚拟环境的作用：

项目隔离：每个项目拥有独立的依赖树，互不干扰、确保不同项目的依赖互不干扰。
避免污染：防止全局 python 环境被实验性包破坏、避免全局环境被污染，保持系统 python 的稳定性。
依赖管理：通过 requirements.txt 精确记录和复现环境、通过 requirements.txt 轻松在其他机器上复现完全一致的开发环境。
安全测试：放心测试新库，不影响其他项目或系统工具、可以在隔离环境中安全地测试新库或升级操作，失败只需删除环境即可，不影响系统

2. 发展历史

早期痛点: 在虚拟环境工具出现之前，所有 python 项目共享系统全局的 site-packages。如果项目 a 需要 django 2.0，而项目 b 需要 django 4.0，开发者将无法在同一台机器上同时开发这两个项目，强行安装会导致版本冲突（dependency hell）。
virtualenv 时代: 早期社区主要依赖第三方工具 virtualenv 来解决这一问题，它功能强大但需要额外安装。
venv 的诞生 (python 3.3+): 为了标准化和简化流程，python 3.3 引入了内置模块 venv (pep 405)。它成为了官方推荐的标准工具，无需额外安装即可使用，轻量且稳定。
现代生态: 如今，venv 是日常开发的首选，而 conda 则在数据科学领域占据主导，poetry 和 pipenv 等工具则在依赖管理层面提供了更高级的封装。

python 2.x 时代：主要依赖第三方工具 virtualenv（由 ian bicking 开发）。
python 3.3+ (2012)：pep 405 被接受，venv 模块作为标准库内置，无需额外安装。
python 3.4+：ensurepip 模块加入，虚拟环境默认包含 pip。
现代趋势：venv 成为官方推荐标准，virtualenv 主要用于兼容旧版本或特殊需求；conda 在数据科学领域流行。

3. 发展方向

更轻量级：减少基础镜像大小。
更好的集成：与 ide（vs code, pycharm）深度整合。
可复现性：结合 pip-tools, poetry, pipenv 等工具实现更严格的依赖锁定。

标准化: 成为所有 python 项目的标准配置（通常命名为 .venv）。
集成化: 现代 ide (vs code, pycharm) 自动识别并集成 venv 管理。
轻量化: 相比 conda，venv 更专注于 python 包本身，启动更快，占用更小。

二、基本语法结构与跨平台操作

1. 核心命令速查表

操作	windows (cmd/powershell)	macos / linux
创建环境	`python -m venv .venv`	`python3 -m venv .venv`
激活环境	`.venv\scripts\activate`	`source .venv/bin/activate`
退出环境	`deactivate`	`deactivate`
安装包	`pip install <package>`	`pip install <package>`
查看已安装包	`pip list`	`pip list`
导出依赖	`pip freeze > requirements.txt`	`pip freeze > requirements.txt`
安装依赖	`pip install -r requirements.txt`	`pip install -r requirements.txt`
删除环境	`rmdir /s /q .venv`	`rm -rf .venv`

命名约定：业界通常将虚拟环境命名为 .venv（加点表示隐藏目录），并在 .gitignore 中忽略它。

2. 详细操作步骤

step 1: 检查 python 版本

确保安装了 python 3.3+（推荐 3.8+）。

python3 --version
# 或 windows
python --version

step 2: 创建虚拟环境

python 3.3+ 内置 venv 模块，无需安装。

通用命令:

python3 -m venv <环境名称>

注：在 windows 上，如果 python3 不可用，请尝试 python。

常用命名约定:

.venv: 最推荐的命名，以 . 开头表示隐藏文件夹，保持目录整洁。
venv: 传统命名。
env: 简短命名。

示例:

mkdir my_project
cd my_project
python3 -m venv .venv

进入项目目录，执行创建命令：

# macos/linux
python3 -m venv .venv
# windows
python -m venv .venv

目录结构解析：

bin/ (unix) 或 scripts/ (windows)：存放激活脚本和解释器。
lib/ 或 lib/：存放安装的第三方库。
pyvenv.cfg：配置文件，指向基础 python 解释器。

step 3: 激活虚拟环境 (关键步骤)

激活后，命令行提示符前会出现环境名称（如 (.venv)），此时所有的 python 和 pip 命令都指向虚拟环境内部。
macos / linux:

source .venv/bin/activate

windows (cmd):

.venv\scripts\activate

windows (powershell):

.venv\scripts\activate.ps1

注：若 powershell 提示执行策略错误，可能需要以管理员身份运行需运行 set-executionpolicy -executionpolicy remotesigned -scope currentuser。

激活成功标志：命令行前出现 (.venv) 前缀。

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

step 4: 管理与安装包

激活后，python 和 pip 命令自动指向虚拟环境内部。

# 安装单个包
pip install requests
# 安装多个包
pip install requests pandas numpy
# 安装指定版本
pip install django==3.2.12
# 查看已安装包
pip list
# 升级 pip
pip install --upgrade pip

step 5: 导出与复现依赖

导出依赖文件：

pip freeze > requirements.txt

复现(从文件安装依赖)（在新机器或新环境中）：

pip install -r requirements.txt

提示：国内用户可使用镜像源加速：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

step 6: 退出虚拟环境

退出：完成工作后，随时可以退出：

deactivate

退出后，命令行提示符恢复正常，python 和 pip 回归系统全局版本。

step 7: 删除虚拟环境

虚拟环境只是一个文件夹，删除它即删除了环境。

确保先退出环境: deactivate

macos / linux:

rm -rf .venv

windows (cmd):

rmdir /s /q .venv

windows (powershell):

remove-item -recurse -force .venv

三、进阶使用与实际场景

1. 指定 python 版本创建环境

若系统安装了多个 python 版本（如 3.8, 3.9, 3.10），可指定解释器：

# 使用 python 3.8 创建环境
python3.8 -m venv .venv38
# 激活后检查版本
source .venv38/bin/activate
python --version  # 输出: python 3.8.x

2. 继承系统包 (system site packages)

默认情况下，虚拟环境无法访问全局安装的包。如果需要（例如全局安装了某些难以编译的系统级库），可以使用 --system-site-packages。
默认情况下，虚拟环境隔离系统包。若需访问系统已安装的全局包（如某些系统工具依赖）：

python3 -m venv --system-site-packages .venv

慎用：可能破坏隔离性。
警告：这会破坏环境的纯净性，通常不推荐，除非明确知道自己在做什么。

3. 不带 pip 的环境

用于构建极度精简的环境（较少见）。
极简模式，手动安装 pip：

python3 -m venv --without-pip .venv

4. 实际场景：django 项目开发

# 1. 创建项目目录
mkdir my_blog && cd my_blog
# 2. 创建并激活环境
# macos/linux
python3 -m venv .venv
source .venv/bin/activate
# windows cmd
# python -m venv .venv
# .venv\scripts\activate.bat
# windows powershell
# python -m venv .venv
# .venv\scripts\activate.ps1
# 3. 升级 pip (好习惯，避免安装旧版包)
pip install --upgrade pip
# 4. 安装 django
pip install django==4.2
# 5. 创建 django 项目 (注意末尾的 . 表示在当前目录)
django-admin startproject config .
# 6. 【可选】创建第一个 app (这才是开发步骤，而不是重复 startproject)
python manage.py startapp blog
# 7. 开发阶段...
# (在此阶段你可能还会安装其他包，例如: pip install pillow)
# echo "hello world" >> blog/views.py  (模拟写代码)
# 8. 开发完成后，统一导出所有依赖 (覆盖之前的记录)
pip freeze > requirements.txt
# 9. 运行开发服务器测试
python manage.py runserver
# 10. 完成工作，退出环境
deactivate
# ==========================================
# 同事协作场景 (拉取代码后)
# ==========================================
# 同事只需运行：
git clone <你的仓库地址>
cd my_blog
# 1. 创建环境
python3 -m venv .venv
# 2. 激活环境
source .venv/bin/activate  # windows 对应用户的命令
# 3. 一键还原所有依赖 (包括 django 和你后来加的 pillow 等)
pip install -r requirements.txt
# 4. 运行
python manage.py runserver

5. 实际场景：数据科学环境

# 创建专门用于数据分析的环境
python3 -m venv data-env
source data-env/bin/activate
# 安装重型科学计算库
pip install numpy pandas scikit-learn matplotlib jupyter
# 启动 jupyter notebook
jupyter notebook

6: ide 集成 (vs code / pycharm)

vs code: 打开项目后，右下角点击 python 版本号，选择 .venv/bin/python，ide 会自动识别并使用该环境进行 linting 和调试。
pycharm: 新建项目时直接选择 “new environment using virtualenv”，ide 会自动处理创建和激活过程。

四、致命陷阱与避坑指南

陷阱 1：忘记激活环境

这是新手最常犯的错误。在未激活环境下安装的包会进入全局环境，导致虚拟环境失去意义。

检查方法: 看命令行前是否有 (.venv) 前缀，或运行 which python (linux/mac) / where python (windows) 确认路径是否指向 .venv 目录。

现象：安装包到了全局环境，项目运行时却报错 modulenotfounderror。
解决：养成习惯，进入项目目录第一件事就是检查命令行是否有 (.venv) 前缀。

which python  # unix
where python  # windows
# 确认路径指向 .venv 目录

陷阱 2：将虚拟环境提交到 git

虚拟环境包含大量二进制文件和特定路径配置，体积大且不可移植。
现象：仓库体积巨大，且在其他机器上因路径硬编码无法运行。
解决：务必在 .gitignore 中添加：

.venv/
venv/
env/
*.pyc
__pycache__/

陷阱 3：移动虚拟环境

虚拟环境中的许多脚本（如 activate 和 shebang 行）包含绝对路径。
现象：将整个 .venv 文件夹复制到另一台电脑或不同路径，导致无法激活。
原因：虚拟环境中的脚本（如 activate）和解释器路径是硬编码的绝对路径。
解决：不要移动环境。如果项目移动了，删除旧的 .venv，在新位置重新创建并安装依赖。在新位置重新创建环境并 pip install -r requirements.txt。

陷阱 4：windows powershell 激活失败

在 powershell 中运行 .venv\scripts\activate 可能会报错：“在此系统上禁止运行脚本”。
现象：运行 activate.ps1 提示“在此系统上禁止运行脚本”。
解决 - 1: 以管理员身份运行 powershell，执行 set-executionpolicy remotesigned，或者直接使用 .venv\scripts\activate.ps1。
解决 - 2：以管理员身份打开 powershell，执行：

set-executionpolicy -executionpolicy remotesigned -scope currentuser

陷阱 5：依赖版本冲突

现象：requirements.txt 中未锁定具体版本（如只写了 requests 而非 requests==2.28.0），导致不同时间安装版本不一致。
解决：始终使用 pip freeze 生成带版本号的文件，或使用 pip-tools 进行更精细的管理。

陷阱 6：混淆pip和pip3

现象：在某些 linux 发行版中，pip 可能指向 python 2，而 pip3 指向 python 3。
解决：在虚拟环境激活后，直接使用 pip 即可（它会自动指向环境内的正确版本）。若未激活，建议使用 python3 -m pip。

陷阱 7: 混淆requirements.txt和setup.py

requirements.txt: 用于锁定应用运行的确切环境（包含所有依赖及其版本），主要用于部署和开发环境复现。
setup.py / pyproject.toml: 用于定义库本身的元数据和依赖关系，主要用于发布包到 pypi。
建议: 应用项目主要维护 requirements.txt。

五、最佳实践总结

一文一环境：每个独立项目都必须有专属虚拟环境。
命名规范：统一使用 .venv 作为目录名，方便 ide 自动识别。
忽略提交：确保 .gitignore 中包含虚拟环境目录。
锁定版本：requirements.txt 必须包含具体版本号（==）。
定期清理：删除不再维护的项目的虚拟环境，释放磁盘空间。
自动化：在 ci/cd 流程中自动创建环境并安装依赖，确保测试一致性。

建议：
“虚拟环境不是可选项，而是 python 开发的标配。从今天开始，告别全局安装，拥抱隔离与纯净！”
掌握 venv 是 python 开发者的基本功。遵循 “每个项目一个环境”、“不提交环境目录”、“始终记录依赖” 这三条原则，能让你的开发之路更加顺畅，避免绝大多数依赖冲突问题。

掌握 venv，你就掌握了 python 工程化的第一把钥匙。

以上就是python虚拟环境(venv)的全面使用指南的详细内容，更多关于python虚拟环境venv使用的资料请关注代码网其它相关文章！

Python虚拟环境(venv)的全面使用指南

2026年03月24日 • Python •我要评论

摘要