Python venv:虚拟环境完全指南 (2026)
关于 Python 虚拟环境,你所需要了解的一切
开始使用 Hypereal 构建
通过单个 API 访问 Kling、Flux、Sora、Veo 等。免费积分开始,扩展到数百万。
无需信用卡 • 10万+ 开发者 • 企业级服务
Python venv:虚拟环境完整指南 (2026)
虚拟环境是每位 Python 开发者必须掌握的基础知识之一。它们旨在隔离项目依赖,确保为一个项目安装包时不会破坏另一个项目。Python 内置的 venv 模块是创建虚拟环境的标准方式,本指南涵盖从基础到高级工作流的所有内容。
为什么使用虚拟环境?
如果不使用虚拟环境,所有 Python 包都会安装在全局环境中。这会导致冲突:
# 项目 A 需要 Django 4.2
pip install django==4.2
# 项目 B 需要 Django 5.1
pip install django==5.1
# 这会覆盖 Django 4.2 —— 项目 A 现在运行崩溃了
虚拟环境通过为每个项目提供独立的包集合来解决这个问题:
project-a/
.venv/ # 包含 Django 4.2
manage.py
project-b/
.venv/ # 包含 Django 5.1
manage.py
每个 .venv 目录都包含自己的 Python 解释器和包,彼此完全独立。
创建虚拟环境
基本用法
# 进入你的项目目录
cd /path/to/your/project
# 创建一个名为 .venv 的虚拟环境
python3 -m venv .venv
约定俗成的做法是将目录命名为 .venv(带有前导点以便隐藏)。有些团队使用 venv、env 或 .env,但 .venv 是目前应用最广泛的标准。
指定 Python 版本
# 使用特定的 Python 版本
python3.12 -m venv .venv
# 或者在有多个版本的系统上
/usr/local/bin/python3.13 -m venv .venv
虚拟环境将使用你调用它时所用的 Python 二进制文件。
创建了什么
.venv/
bin/ # 脚本 (activate, pip, python) -- Linux/macOS
Scripts/ # 脚本 (activate, pip, python) -- Windows
lib/
python3.12/
site-packages/ # 安装的包存放在这里
include/ # 用于编译扩展的 C 头文件
pyvenv.cfg # 配置文件
激活虚拟环境
macOS / Linux
source .venv/bin/activate
Windows (PowerShell)
.venv\Scripts\Activate.ps1
Windows (命令提示符)
.venv\Scripts\activate.bat
Fish Shell
source .venv/bin/activate.fish
激活后,你的终端提示符会发生变化,显示环境名称:
(.venv) user@machine:~/project$
验证激活状态
# 检查 python 是否指向 venv
which python
# 输出: /path/to/project/.venv/bin/python
# 检查 pip 是否指向 venv
which pip
# 输出: /path/to/project/.venv/bin/pip
# 确认 Python 路径
python -c "import sys; print(sys.prefix)"
# 输出: /path/to/project/.venv
安装包
在激活虚拟环境后,pip install 仅将包安装到该 venv 中:
# 安装单个包
pip install requests
# 安装特定版本
pip install django==5.1.2
# 安装多个包
pip install flask sqlalchemy celery
# 从需求文件安装
pip install -r requirements.txt
创建 requirements.txt
# 将当前安装的包冻结到 requirements.txt
pip freeze > requirements.txt
这会生成如下内容的文件:
certifi==2024.12.14
charset-normalizer==3.4.1
django==5.1.2
idna==3.10
requests==2.32.3
sqlparse==0.5.3
urllib3==2.3.0
使用 requirements.txt
# 从需求文件安装所有依赖
pip install -r requirements.txt
这是团队成员复现你完全一致的环境的方式。
退出虚拟环境
deactivate
你的提示符将恢复正常,python 和 pip 将重新指向系统级安装。
虚拟环境最佳实践
1. 始终将 .venv 添加到 .gitignore
虚拟环境永远不应该提交到版本控制系统中:
# .gitignore
.venv/
venv/
env/
__pycache__/
*.pyc
应该提交 requirements.txt(或 pyproject.toml)。团队成员通过需求文件重新创建 venv。
2. 在现代项目中使用 pyproject.toml
对于 2026 年的新项目,推荐使用 pyproject.toml 而非 requirements.txt:
[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.12"
dependencies = [
"django>=5.1",
"requests>=2.32",
"celery>=5.4",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0",
"ruff>=0.8",
"mypy>=1.13",
]
安装命令:
pip install -e . # 安装项目 + 依赖
pip install -e ".[dev]" # 包含开发环境依赖
3. 为生产环境锁定依赖版本
为生产部署使用 pip freeze 或 lock 文件:
# 生成完全锁定的 lock 文件
pip freeze > requirements-lock.txt
# 对于开发环境,可以保持较宽松的版本范围
# requirements.txt
django>=5.1,<6.0
requests>=2.32
4. 每个项目使用一个虚拟环境
切勿在项目之间共享虚拟环境:
# 正确:每个项目都有自己的 venv
project-a/.venv/
project-b/.venv/
# 错误:共享 venv
shared-env/ # 两个项目共用 -- 会导致冲突
5. IDE 集成
VS Code / Cursor
VS Code 和 Cursor 会自动检测项目根目录下的 .venv。如果没有检测到:
- 打开命令面板 (
Cmd+Shift+P) - 输入:Python: Select Interpreter
- 从
.venv/bin/python选择解释器
或者添加到 .vscode/settings.json:
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}
PyCharm
PyCharm 会自动检测虚拟环境。如需手动配置:
- 进入 Settings > Project > Python Interpreter
- 点击齿轮图标 > Add
- 选择 Existing Environment
- 浏览至
.venv/bin/python
常见任务
在 venv 内部升级 pip
python -m pip install --upgrade pip
列出已安装的包
pip list
# 仅显示你安装的包(不包括依赖项)
pip list --not-required
检查过时的包
pip list --outdated
卸载包
pip uninstall requests
重新创建虚拟环境
如果你的 venv 损坏或想要重新开始:
# 删除旧的 venv
rm -rf .venv
# 创建一个新的
python3 -m venv .venv
# 激活并重新安装
source .venv/bin/activate
pip install -r requirements.txt
venv 与其他工具对比
| 工具 | 内置 | Lock 文件 | 多 Python 版本支持 | 速度 | 适用场景 |
|---|---|---|---|---|---|
| venv | 是 | 否 (使用 pip freeze) | 否 (需手动) | 快 | 简单项目 |
| uv | 否 (pip 安装) | 是 | 是 | 极快 | 现代 Python 开发 |
| Poetry | 否 (pip 安装) | 是 | 否 | 中 | 库作者 |
| Conda | 否 (独立安装) | 是 | 是 | 慢 | 数据科学 |
| pipenv | 否 (pip 安装) | 是 | 否 | 慢 | 旧项目维护 |
| hatch | 否 (pip 安装) | 是 | 是 | 快 | 符合 PEP 标准的项目 |
什么时候使用 venv
在以下情况下使用 venv:
- 你希望零额外依赖(它是 Python 内置的)
- 你的项目结构简单,依赖树不复杂
- 你正在学习 Python 并希望了解基础原理
- 你的团队已经在使用
requirements.txt
什么时候改用 uv
在 2026 年,uv 已成为最受欢迎的替代方案。它是一个极速的替代工具:
# 安装 uv
pip install uv
# 创建 venv (比 venv 快 10 倍)
uv venv
# 安装包 (比 pip 快 100 倍)
uv pip install -r requirements.txt
# 使用 lock 文件同步依赖
uv sync
如果速度对你很重要,并且你不介意多使用一个工具,uv 是现代化的选择。
常见问题排查
"python3 -m venv" 返回错误
在 Ubuntu/Debian 上:
# 安装 venv 模块 (默认可能未包含)
sudo apt install python3-venv
在 Fedora/RHEL 上:
sudo dnf install python3-venv
找不到激活脚本
# 检查 venv 是否正确创建
ls .venv/bin/activate
# 如果缺失,重新创建 venv
rm -rf .venv
python3 -m venv .venv
Windows 上的 "Permission denied" (权限拒绝)
以管理员身份运行 PowerShell 并执行:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
激活 venv 后包仍安装在全局
检查激活是否真的生效:
echo $VIRTUAL_ENV
# 应该输出: /path/to/project/.venv
# 如果为空,则激活失败 -- 请重试
source .venv/bin/activate
OS 更新后 Python 版本不匹配
Python 更新后,你的 venv 可能会指向旧的解释器:
# 检查 venv 的 Python 版本
.venv/bin/python --version
# 如果报错或显示错误版本,请重新创建
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
快速参考表
| 命令 | 描述 |
|---|---|
python3 -m venv .venv |
创建虚拟环境 |
source .venv/bin/activate |
激活 (macOS/Linux) |
.venv\Scripts\activate |
激活 (Windows) |
deactivate |
退出激活状态 |
pip install package |
安装包 |
pip freeze > requirements.txt |
导出依赖 |
pip install -r requirements.txt |
从文件安装 |
pip list |
列出已安装的包 |
pip list --outdated |
检查更新 |
rm -rf .venv |
删除 venv |
总结
Python 的 venv 模块简单、可靠且内置于语言中。对于大多数项目来说,它是管理隔离依赖所需的全部工具。开始每个新项目时,请先创建一个 .venv,将其添加到 .gitignore,并提交你的 requirements.txt 或 pyproject.toml,以便你的团队可以复现该环境。
如果你正在构建涉及 AI 生成内容的 Python 应用程序,Hypereal AI 提供对 Python 友好的 API,涵盖图像生成、视频创建、唇形同步和数字人头像。欢迎免费注册以探索 API。
