为 Python 项目创建独立虚拟运行环境 (venv)
目录
为什么需要虚拟环境
- 依赖隔离：不同项目依赖的库及其版本可能互不兼容，虚拟环境可避免全局污染。
- 多版本 Python：配合 pyenv 等工具，可为每个项目选用最合适的 Python 版本。
- 可移植性：团队成员或 CI/CD 只需
python -m venv与pip install -r requirements.txt即可重建相同环境。
Python 3.3 之前可使用
virtualenv，参考 用 VirtualEnv 为项目创建独立运行环境。
venv 与其它方案对比
| 方案 | 依赖隔离 | 解释器隔离 | 额外依赖 | 典型场景 |
|---|---|---|---|---|
venv (内置) | ✅ | ❌ (复用系统解释器) | 无 | 常规开发、CI/CD |
virtualenv | ✅ | ✅ | virtualenv 包 | 兼容旧版 Python (<3.3) |
| Conda | ✅ | ✅ | Anaconda/Miniconda | 数据科学、需 C 库打包 |
快速上手：创建 & 激活虚拟环境
1. Linux / macOS
# 在项目根目录创建 .venv 文件夹 (推荐隐藏)
python3 -m venv .venv
# 激活 (bash/zsh)
source .venv/bin/activate
# 若使用 fish
# source .venv/bin/activate.fish
# 提示符变为 (.venv) ➜ 表示已激活
# 安装依赖示例
pip install requests2. Windows PowerShell / CMD
# 创建
py -m venv .venv
# 激活
.\.venv\Scripts\Activate.ps1 # PowerShell
# 或
.\.venv\Scripts\activate.bat # CMD若遇 execution policy 限制，管理员 PowerShell 运行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。
3. 查看当前解释器路径
which python # *nix
where python # Windows应输出项目 .venv 路径。
4. 在 IDE 中自动激活虚拟环境
- VS Code：
Ctrl/Cmd + Shift + P→ Python: Select Interpreter 选中.venv中的解释器。 - PyCharm：
Settings / Preferences > Python Interpreter > Add选择 Existing environment 并指向.venv/bin/python。
常用操作速查
| 操作 | 命令 | 说明 |
|---|---|---|
| 升级 pip | python -m pip install --upgrade pip | pip 的升级 |
| 安装依赖 | pip install package-name | 查看 pip 使用教程 |
| 导出依赖 (锁定) | pip freeze > requirements.txt | 用 pip freeze 导出依赖清单 |
| 从文件安装依赖 | pip install -r requirements.txt | 参见 pip 从 requirements 批量安装 |
| 停用/退出虚拟环境 | deactivate | 还原 PATH 环境变量 |
| 删除虚拟环境 | rm -rf .venv (*nix) / rmdir /s .venv (Win) | 完全移除 |
.gitignore 示例
.venv/
__pycache__/
常见问题 FAQ
为何激活后仍使用系统 pip?
确认已执行source .venv/bin/activate(或 Windows 对应脚本)。如果使用 VS Code，检查 Python: Select Interpreter 是否指向.venv。如何为 VS Code 自动激活虚拟环境?
在工作区设置加入：
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"需要多版本 Python?
使用 pyenv 安装所需版本后，再执行pyenv local 3.12.0 && python -m venv .venv。激活脚本下载后报“无执行权限”
Linux/macOS 下执行chmod +x .venv/bin/activate赋予可执行权限。如何在 CI 中缓存虚拟环境?
将.venv放到缓存目录并在安装依赖前恢复，示例见 GitHub Actionsactions/cache的官方用法。