Python venv：虚拟环境完全指南 (2026)

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。如果没有检测到：

1. 打开命令面板 (Cmd+Shift+P)
2. 输入：Python: Select Interpreter
3. 从 .venv/bin/python 选择解释器

或者添加到 .vscode/settings.json：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

PyCharm

PyCharm 会自动检测虚拟环境。如需手动配置：

1. 进入 Settings > Project > Python Interpreter
2. 点击齿轮图标 > Add
3. 选择 Existing Environment
4. 浏览至 .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。