Python 项目最常见的问题之一是依赖混乱：本地能运行，服务器不能运行；A 项目升级了某个库，B 项目突然报错；系统 Python 被安装了大量第三方包，最后不敢删除也不敢升级。

解决这类问题的基础做法是使用虚拟环境，并把依赖版本记录下来。本文以标准库 venv 和 pip 为主，介绍一套简单可靠的依赖管理流程。

为什么需要虚拟环境

虚拟环境会为每个项目创建独立的 Python 包安装目录。项目安装的第三方库只影响当前环境，不污染系统 Python，也不会影响其他项目。

适合使用虚拟环境的场景包括：

  • Web 服务项目。
  • 数据处理脚本。
  • 机器学习实验。
  • 定时任务。
  • 需要固定版本依赖的旧项目。

即使只是一个小脚本，只要安装了第三方库，也建议创建虚拟环境。

创建虚拟环境

在项目根目录执行：

1
python3 -m venv .venv

激活环境：

1
source .venv/bin/activate

激活后终端前面通常会出现 (.venv)。此时执行：

1
2
which python
which pip

路径应该指向当前项目的 .venv 目录。

Windows PowerShell 中激活方式不同：

1
.\.venv\Scripts\Activate.ps1

如果提示执行策略限制，需要按公司或个人电脑的安全规范调整 PowerShell 策略。

安装依赖

激活虚拟环境后，安装依赖：

1
pip install requests fastapi uvicorn

查看当前安装包：

1
pip list

导出依赖：

1
pip freeze > requirements.txt

其他机器可以通过下面命令安装同样的依赖：

1
pip install -r requirements.txt

requirements.txt 应该提交到 Git，而 .venv 目录不应该提交。可以在 .gitignore 中加入：

1
2
3
.venv/
__pycache__/
*.pyc

requirements.txt 的维护方式

pip freeze 会导出所有直接和间接依赖，版本非常明确，适合部署环境复现。但它也可能包含一些临时实验安装的包。

推荐做法是维护两个文件：

1
2
requirements.in
requirements.txt

requirements.in 记录直接依赖：

1
2
3
fastapi
uvicorn
requests

requirements.txt 记录锁定后的完整依赖：

1
2
pip install pip-tools
pip-compile requirements.in

如果项目不想引入额外工具，也可以只使用 requirements.txt，但每次新增依赖时要检查是否把无关包也导入了。

固定版本还是放宽版本

部署型项目建议固定版本，例如：

1
2
3
fastapi==0.115.0
uvicorn==0.30.6
requests==2.32.3

这样可以减少“今天安装”和“下个月安装”得到不同依赖树的问题。

库项目可以适当使用范围版本，例如：

1
requests>=2.31,<3.0

因为库项目需要兼容使用者的环境，不能过度锁死依赖。

升级依赖

升级依赖不要在生产环境临时执行。建议在本地或测试环境按流程升级：

1
2
3
pip install --upgrade requests
pip freeze > requirements.txt
pytest

如果升级后测试通过，再提交依赖变更。对于 Web 服务，还应该观察启动日志、接口冒烟测试和关键任务。

机器学习项目更要谨慎升级 PyTorch、CUDA、NumPy、Pandas 等依赖，因为二进制兼容和 API 行为变化都可能影响训练结果。

查看依赖冲突

安装后可以使用：

1
pip check

它会检查已安装包之间的版本约束。如果发现冲突，应优先调整顶层依赖版本，而不是手动修改 site-packages。

查看某个包的信息：

1
pip show fastapi

查看依赖树可以安装：

1
2
pip install pipdeptree
pipdeptree

依赖冲突复杂时，依赖树比 pip list 更容易定位问题来源。

项目启动建议

README 中应该写清楚最小启动步骤：

1
2
3
4
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py

如果项目需要环境变量，也应该提供 .env.example，但不要提交真实密钥。

常见问题

第一个问题是忘记激活虚拟环境，结果把包装到系统 Python。安装前使用 which pip 检查路径。

第二个问题是把 .venv 提交到 Git。虚拟环境包含大量机器相关文件，应该只提交依赖清单。

第三个问题是在多个 Python 版本之间混用依赖。创建虚拟环境时要确认 Python 版本，例如 python3.11 -m venv .venv。

第四个问题是部署环境直接 pip install 最新版本。生产部署应使用锁定版本，降低不可控变化。

小结

Python 依赖管理的基础是虚拟环境加依赖清单。每个项目独立 .venv，依赖写入 requirements.txt，敏感配置通过环境变量传入，升级依赖走测试流程。只要这些习惯稳定下来，多项目开发和服务器部署都会简单很多。