Python 虚拟环境与依赖管理完全指南

Python 项目依赖管理是开发者日常工作中的高频场景。从 virtualenv 到 Poetry，从 pip 到 uv，工具不断演进。本文系统梳理 Python 环境管理最佳实践，帮你告别”在我机器上能跑”的困境。

一、为什么需要虚拟环境

Python 全局安装包会导致版本冲突：项目A需要 Django 4.2，项目B需要 Django 3.2，两者无法共存于同一 Python 环境。虚拟环境为每个项目创建独立的 Python 解释器和包目录，彻底解决版本冲突问题。

二、venv（内置，推荐新手）

python -m venv .venv           # 创建虚拟环境
source .venv/bin/activate      # 激活（Linux/Mac）
.venv\Scripts\activate         # 激活（Windows）
pip install -r requirements.txt
deactivate                     # 退出虚拟环境

将 .venv 加入 .gitignore，只提交 requirements.txt。

三、pip 最佳实践

pip install requests            # 安装包
pip install requests==2.31.0   # 安装指定版本
pip freeze > requirements.txt  # 导出依赖
pip install -r requirements.txt # 安装所有依赖
pip list --outdated            # 查看可更新的包
pip install --upgrade pip      # 升级 pip 本身

注意：直接 pip freeze 会包含所有间接依赖，推荐用 pip-tools 管理直接依赖和锁定文件。

四、Poetry（现代化依赖管理）

Poetry 是目前最推荐的 Python 项目管理工具，解决了 pip 的诸多痛点：

pip install poetry
poetry new my-project          # 创建新项目
poetry add requests            # 添加依赖
poetry add pytest --dev        # 添加开发依赖
poetry install                 # 安装所有依赖
poetry run python main.py      # 在虚拟环境中运行
poetry shell                   # 进入虚拟环境 shell
poetry build                   # 打包项目
poetry publish                 # 发布到 PyPI

Poetry 自动生成 poetry.lock 文件锁定精确版本，确保团队环境完全一致。

五、pyenv（多版本管理）

当需要同时维护 Python 3.9、3.11、3.12 等多个版本时，pyenv 是最佳选择：

pyenv install 3.12.0           # 安装 Python 3.12
pyenv global 3.12.0           # 设置全局版本
pyenv local 3.11.0            # 设置项目本地版本（写入 .python-version）
pyenv versions                # 列出所有已安装版本

六、uv（新一代极速工具）

uv 是 2024 年新兴的 Python 包管理工具，用 Rust 编写，速度比 pip 快 10-100 倍：

pip install uv
uv venv .venv                  # 创建虚拟环境（极速）
uv pip install requests        # 安装包（速度惊人）
uv pip sync requirements.txt  # 同步依赖

七、Docker 统一环境

对于生产部署，将 Python 应用容器化是最彻底的环境隔离方案，完全消除”环境差异”问题。配合多阶段构建可以得到精简的生产镜像。

总结

新项目推荐使用 Poetry，老项目继续用 venv + pip-tools，多版本场景加上 pyenv。关键原则：每个项目独立环境，锁定依赖版本，将环境配置纳入版本控制。