2025/10/10大约 4 分钟
1. 定义与价值
核心定义
requirements.txt 是 Python 项目的依赖声明文件，以文本格式记录项目运行所需的第三方包及其精确版本。
定位与作用
| 定位 | 作用 |
|---|---|
| 依赖清单 | 明确列出项目依赖的所有包及其版本，避免环境差异导致运行失败。 |
| 环境迁移 | 通过一条命令快速重建项目环境（开发、测试、生产）。 |
| 协作标准 | 确保团队成员或部署服务器使用完全一致的依赖版本。 |
解决的问题
- 环境不一致：解决"在我机器上能运行"的问题。
- 依赖冲突：锁定版本避免包之间不兼容。
- 部署效率：自动化安装依赖，减少手动配置。
2. 常用命令
生成 requirements.txt
# 方法1：仅生成项目实际引用的包（推荐）
pip install pipreqs
pipreqs . --encoding=utf8 --force
# 方法2：生成当前环境所有安装的包（可能包含无关包）
pip freeze > requirements.txt安装依赖
# 从文件安装依赖（使用国内镜像加速）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple3. 使用指南
安装与配置
工具安装：
pip install pipreqs # 用于生成精准依赖
使用流程
- 生成文件：在项目根目录执行
pipreqs或pip freeze。 - 检查文件：确认版本范围合理（如
numpy==1.21.0或flask>=2.0.0）。 - 安装依赖：在新环境中运行
pip install -r requirements.txt。
注意事项
文件位置：必须放在项目根目录，否则需指定路径：
pip install -r /path/to/requirements.txt编码问题：使用
--encoding=utf8避免中文路径报错。版本范围：
==1.2.3：锁定精确版本（生产环境推荐）。>=1.2.0,<2.0.0：允许安全更新。
多环境管理：
requirements/ base.txt # 公共依赖 dev.txt # 开发环境（包含测试工具） prod.txt # 生产环境
4. 竞品对比
| 工具/方法 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| pipreqs | 仅生成项目实际引用的包 | 需额外安装；可能漏掉深层依赖 | 精准管理项目依赖 |
| pip freeze | 无需安装；包含环境所有包 | 包含无关包（污染环境） | 复制完整环境 |
| pip-tools | 支持依赖压缩和哈希校验 | 配置复杂 | 需要高安全性的项目 |
| 手动维护 | 完全可控 | 易出错；维护成本高 | 依赖极少的小型项目 |
5. 常见问题解决
Q1：执行 pip install -r requirements.txt 报错文件不存在
原因：文件路径错误或文件名拼写错误。
解决：
# 确认文件名拼写（推荐全小写）
ls | grep requirements.txt
# 指定绝对路径
pip install -r $(pwd)/requirements.txtQ2：安装时版本冲突
原因：依赖包版本不兼容。
解决：
- 检查冲突包的版本范围。
- 使用
pip check定位冲突。 - 升级或降级冲突包后重新生成文件。
Q3：生成文件包含无关包
原因：使用 pip freeze 混入了全局环境包。
解决：
使用虚拟环境隔离：
python -m venv venv # 创建虚拟环境 source venv/bin/activate # 激活环境 pip install pipreqs # 在虚拟环境中操作
6. 最佳实践
隔离环境：始终在虚拟环境（如
venv或conda）中管理依赖。精准生成：优先用
pipreqs生成最小依赖集。版本锁定：生产环境使用
==锁定版本，避免自动升级破坏兼容性。分环境管理：
# 生产环境安装 pip install -r requirements/prod.txt与
setup.py配合：requirements.txt：用于部署安装。setup.py：用于打包分发（定义包元数据和依赖）。
校验依赖：定期运行
pip check检测冲突。
总结
requirements.txt 是 Python 项目的依赖蓝图，其核心价值在于 环境可复现性 和 协作标准化。通过结合虚拟环境和精准依赖生成（pipreqs），可有效避免"依赖地狱"。对于复杂项目，推荐采用分环境管理策略，并定期审计依赖安全性。
关键口诀：
虚拟环境隔离 +pipreqs精准生成 + 生产环境版本锁定 = 可靠依赖管理