Python 项目依赖管理

Python 项目依赖管理

引言

在 Python 项目开发中，依赖管理是一个至关重要的环节。如果没有规范化的依赖管理，可能会导致以下问题：

1. 避免版本冲突，确保环境一致性

• Python 的第三方库会不断更新，新版本可能引入 API 变更、Bug 修复或功能调整。
• 如果用户直接使用 pip install package 安装最新版，可能会因版本不匹配导致项目运行失败。
• requirements.txt 可以精确锁定依赖版本，确保开发、测试和生产环境使用相同的库版本，避免兼容性问题。

2. 便于团队协作与项目部署

• 团队成员或客户在运行项目时，只需执行 pip install -r requirements.txt 即可一键安装所有依赖，无需手动逐个安装，减少环境配置的复杂度。
• 在 Docker 容器化部署、CI/CD 自动化流程中，requirements.txt 是标准化的依赖管理方式。

3. 提高项目的可维护性

• 如果项目依赖发生变化（如新增或升级库），只需更新 requirements.txt，团队成员可以快速同步。
• 当项目需要回滚或复现历史版本时，requirements.txt 可以确保依赖版本与代码版本严格匹配。

4. 防止“在我机器上能跑”的问题

• 开发环境（Dev）、测试环境（Test）、生产环境（Prod）的 Python 版本和依赖库必须保持一致。
• 通过 requirements.txt，可以确保不同环境的依赖完全相同，避免因环境差异导致的运行错误。

什么是 requirements.txt？

requirements.txt 是 Python 项目中的一个文本文件，用于记录项目依赖的所有第三方库及其版本号。它的作用是：

• 管理依赖：方便开发者或用户一键安装所有依赖包。
• 版本控制：确保不同环境（开发、测试、生产）使用相同的库版本，避免兼容性问题。
• 协作共享：其他开发者可以快速搭建相同的 Python 环境。

如何快速使用 requirements.txt

1. 生成 requirements.txt

在项目根目录运行以下命令，自动生成依赖列表：

pip freeze > requirements.txt

这会列出当前 Python 环境中所有已安装的包及其版本，保存到 requirements.txt 文件中。

2. 手动编辑 requirements.txt

如果只需要记录特定依赖，可以手动创建文件并写入内容，例如：

requests==2.31.0
numpy>=1.21.0
pandas
flask~=2.0.1

• ==：严格指定版本。
• >=：最低版本。
• ~=：兼容版本（如 ~=2.0.1 表示 >=2.0.1, <2.1.0）。
• 不写版本：安装最新版（不推荐，可能导致版本冲突）。

3. 安装依赖

其他人或新环境可通过以下命令一键安装所有依赖：

pip install -r requirements.txt

1. 区分开发和生产环境**

• requirements-dev.txt：开发专用依赖（如测试框架、代码检查工具）。

• requirements-prod.txt：生产环境核心依赖。

  安装时指定文件：

pip install -r requirements-dev.txt

2. 使用 pip-tools 管理复杂依赖

# 安装 pip-tools
pip install pip-tools

# 编写 requirements.in（手动声明主依赖）
echo "requests>=2.0" > requirements.in

# 编译生成 requirements.txt
pip-compile requirements.in

3. 从 setup.py 生成依赖

   如果项目有 setup.py，可以通过以下方式生成依赖

# setup.py
from setuptools import setup

setup(
    install_requires=[
        "requests>=2.31.0",
        "numpy>=1.21.0",
    ],
)

​ 然后运行：

pip install -e .

4. 最佳实践

• 使用 == 固定版本，谨慎使用 >= 或 ~=
• 分离开发环境和生产环境
• 使用虚拟环境，避免全局污染
• 定时更新和审计依赖
• 使用 pip-tools 或 poety 进阶管理（后续具体讲）

总结

Python 依赖管理能确保开发、测试、生产环境使用完全相同的依赖版本，避免出现“在我电脑上能跑”的问题，是构成项目统一管理、团队高效协作不可或缺的能力。