在 Python 项目中，requirements.txt 文件用于记录项目依赖的第三方库及其版本，方便其他开发者或部署环境复现相同的依赖环境。以下是生成 requirements.txt 的详细方法，涵盖不同场景和工具：
一、基础方法：使用 pip freeze
适用场景
- 快速生成当前虚拟环境中所有已安装库的依赖列表（包括间接依赖）。
- 适合简单项目或快速导出环境。
步骤
- 激活虚拟环境（推荐）：
bash # Windows (cmd/PowerShell) .\venv\Scripts\activate # macOS/Linux source venv/bin/activate
⚠️ 如果未使用虚拟环境，
pip freeze会导出全局所有包，可能导致污染。
- 生成
requirements.txt：
bash pip freeze > requirements.txt
- 这会创建一个包含所有库及其精确版本的文本文件，例如：
numpy==1.26.4 pandas==2.2.0 requests==2.31.0
- 验证文件：
bash cat requirements.txt # macOS/Linux type requirements.txt # Windows
缺点
- 会包含所有间接依赖（如
numpy的依赖库），可能导致文件臃肿。 - 无法区分直接依赖和间接依赖，可能引入不必要的库。
二、进阶方法：使用 pipreqs（推荐）
适用场景
- 仅生成项目实际使用的库（通过代码静态分析）。
- 避免导出未使用的间接依赖，文件更简洁。
步骤
- 安装
pipreqs：
bash pip install pipreqs
- 扫描项目目录并生成
requirements.txt：
bash pipreqs /path/to/your/project --encoding=utf8 --force
--encoding=utf8：避免中文路径报错。--force：覆盖已存在的文件。- 示例输出：
numpy==1.26.4 pandas==2.2.0
- 验证文件：
- 检查是否仅包含项目代码中实际导入的库（如
import numpy会被记录，但numpy的依赖库不会）。
优点
- 精准控制依赖，避免冗余。
- 适合团队协作或生产环境部署。
三、专业方法：使用 poetry 或 pipenv
适用场景
- 使用现代 Python 包管理工具（如
poetry或pipenv）的项目。 - 需要管理开发依赖（如
pytest）和生产依赖分离。
1. 使用 poetry
- 导出依赖：
bash poetry export -f requirements.txt --output requirements.txt --without-hashes
--without-hashes：省略哈希校验（可选）。- 示例输出：
numpy==1.26.4 pandas==2.2.0 pytest==8.0.0 ; extra == "test" # 开发依赖（如通过 `poetry add pytest --group test` 添加）
- 区分开发依赖：
- 默认情况下，
poetry export会包含所有依赖。若需分离：
bash poetry export -f requirements.txt --output requirements.txt --only main # 仅生产依赖 poetry export -f requirements.txt --output requirements-dev.txt --with dev # 开发依赖
2. 使用 pipenv
- 生成
requirements.txt：
bash pipenv lock -r > requirements.txt
- 这会基于
Pipfile.lock生成精确的依赖列表。
- 分离开发依赖：
bash pipenv lock -r --dev > requirements-dev.txt # 开发依赖
优点
- 自动处理依赖冲突和版本锁定。
- 支持开发/生产环境依赖分离。
四、手动维护 requirements.txt
适用场景
- 项目依赖极少或需要精细控制版本。
- 例如：
numpy>=1.26.0,<2.0.0 # 指定版本范围 pandas==2.2.0 # 固定版本 requests~=2.31.0 # 兼容版本（如 2.31.x）
技巧
- 版本规范：
==：固定版本（如numpy==1.26.4）。>=：最低版本（如pandas>=2.0.0）。~=：兼容版本（如requests~=2.31.0表示 2.31.x）。
- 注释：添加说明（如
# 数据处理库）。 - 分组依赖：用空行分隔不同功能的库（如数据分析、Web 开发）。
五、常见问题解决
1. 文件路径错误
- 问题：
pip freeze或pipreqs报错No such file or directory。 - 解决：确保在项目根目录运行命令，或指定完整路径：
bash pip freeze > /path/to/project/requirements.txt
2. 依赖版本冲突
- 问题：安装
requirements.txt时报错Could not find a version that satisfies...。 - 解决：
- 检查
requirements.txt中是否有冲突的版本范围（如numpy>=2.0.0和pandas<2.0.0可能不兼容）。 - 使用
pip check验证已安装的依赖是否冲突：
bash pip install -r requirements.txt --no-deps # 先跳过依赖安装 pip check
3. 忽略开发依赖
- 问题：不想将
pytest等开发工具部署到生产环境。 - 解决：
- 使用
pipreqs或手动编辑requirements.txt排除开发依赖。 - 或通过
poetry/pipenv分离文件（如requirements-dev.txt）。
六、总结对比
| 方法 | 命令示例 | 优点 | 缺点 |
pip freeze |
pip freeze > requirements.txt |
简单快速 | 包含间接依赖，文件臃肿 |
pipreqs |
pipreqs . --force |
精准导出实际使用的库 | 需额外安装工具 |
poetry export |
poetry export -f requirements.txt |
支持版本范围和分组依赖 | 需学习 poetry 工具 |
pipenv lock -r |
pipenv lock -r > requirements.txt |
自动处理依赖冲突 | 需学习 pipenv 工具 |
| 手动维护 | 编辑 requirements.txt 文件 |
完全控制版本和注释 | 需手动更新，易出错 |
推荐实践
- 新项目：使用
poetry或pipenv管理依赖，自动生成requirements.txt。 - 现有项目：
- 若使用虚拟环境：
pipreqs . --force。 - 若需兼容旧环境：
pip freeze > requirements.txt后手动精简。
- 生产部署：始终测试
requirements.txt在干净环境中的安装：
bash python -m venv test_env source test_env/bin/activate pip install -r requirements.txt
通过以上方法，你可以高效生成符合项目需求的 requirements.txt，确保环境一致性！
