Python 快速生成 requirements.txt 文件的 5 种实用命令

通过结合 shell 的重定向操作符，可将 pip list 的输出保存为文本文件：

pip list > packages.txt

该命令将包名与版本信息写入当前目录下的 packages.txt 文件，适用于生成可读性较强的依赖清单。

生成 requirements 格式

若需构建标准的 requirements.txt，推荐使用冻结功能：

pip freeze > requirements.txt

此方式仅输出通过 pip 安装的包及其精确版本，确保环境重建时的一致性，常用于生产部署。

• > 覆盖写入目标文件
• >> 追加内容至文件末尾

2.3 使用 pipreqs 仅导出项目实际依赖的原理与操作

在 Python 项目中，常因虚拟环境累积大量未使用依赖，导致 requirements.txt 包含冗余包。pipreqs 通过静态分析源码导入语句，仅识别项目中显式引用的第三方库，从而精准生成实际依赖列表。

核心工作原理

pipreqs 扫描项目目录下所有 .py 文件，解析 AST（抽象语法树）提取 import 和 from 语句，过滤出第三方包名，再通过 PyPI 查询对应包名，最终输出最小依赖集。

基本使用命令

pipreqs ./project --encoding=utf8 --force

参数说明：--encoding=utf8 指定文件编码；--force 强制覆盖已存在的 requirements.txt。该命令将生成仅包含项目真实使用的依赖清单，避免手动维护遗漏或冗余。

2.4 conda 环境下导出依赖的等效命令与注意事项

在 conda 环境中，导出依赖关系是项目可复现性的关键步骤。最常用的命令是 conda env export，可生成包含所有通道和版本约束的环境配置。

常用导出命令

conda env export --name myenv > environment.yml

该命令将名为 myenv 的环境导出为 environment.yml 文件。参数 --name 指定环境名，重定向符 > 将输出写入文件。若需排除构建号以增强跨平台兼容性，建议添加 --no-builds 选项：

conda env export --name myenv --no-builds > environment.yml

构建号（如 .0, .h123abc）常导致不同系统间依赖解析失败，去除后提升可移植性。

等效替代方案

也可使用 conda list --export 导出包列表：

conda list --export > requirements.txt

此方式仅保存包名与版本，不包含通道信息，适用于轻量级场景，但功能弱于完整环境导出。

注意事项

• 导出前确保激活目标环境，避免误导出根环境
• 推荐使用 environment.yml 格式进行团队协作
• 定期更新导出文件以反映依赖变更

2.5 利用 poetry export 生成标准 requirements.txt 的方法

在现代 Python 项目中，Poetry 已成为主流的依赖管理工具。然而，在某些部署环境或 CI/CD 流程中，仍需使用传统的 requirements.txt 文件。此时，可通过 poetry export 命令实现依赖格式的兼容转换。

基本导出命令

poetry export -f requirements.txt --output requirements.txt

该命令将当前项目的依赖项导出为标准格式的 requirements.txt。参数说明：

• -f requirements.txt：指定输出格式；
• --output：定义输出文件路径，若省略可直接重定向到文件。

常用选项扩展

• --without-hashes：避免输出依赖哈希值，提升可读性；
• --with-credentials：包含私有源认证信息（谨慎使用）；
• --dev：同时导出开发依赖。

此方法确保了项目在不同工具链间的平滑迁移与协作兼容性。

第三章：虚拟环境中生成依赖文件的最佳实践

3.1 虚拟环境隔离对依赖管理的重要性分析

在多项目共存的开发环境中，全局 Python 包易引发版本冲突。虚拟环境通过进程级隔离，为每个项目提供独立的 site-packages 和解释器路径。

典型冲突场景

• 项目 A 依赖 Django 4.2（需 asgiref ≥3.7）
• 项目 B 依赖 Django 3.2（与 asgiref 3.8 不兼容）

创建与激活示例

# 创建隔离环境
python -m venv myproject_env
# 激活（Linux/macOS）
source myproject_env/bin/activate
# 激活（Windows）
myproject_env\Scripts\activate.bat

该命令生成独立的 bin/（或 Scripts/）目录，其中 python 和 pip 均绑定至当前环境路径，确保 pip install 仅影响本环境。

环境差异对比

3.2 venv + pip freeze 组合操作全流程演示

创建隔离环境

使用 venv 模块创建独立的 Python 运行环境，避免依赖冲突。执行以下命令：

python -m venv myproject_env

该命令生成包含独立解释器和 pip 的目录 myproject_env，确保项目依赖隔离。

激活环境并安装依赖

在 Linux/macOS 系统中运行：

source myproject_env/bin/activate

Windows 用户使用：

myproject_env\Scripts\activate

激活后，通过 pip install 安装所需包，例如：

pip install requests flask

导出依赖清单

使用 pip freeze 将当前环境的包版本导出为标准格式：

pip freeze > requirements.txt

生成的文件内容类似：

此文件可用于在其他环境中精确还原依赖。

3.3 使用 conda 创建独立环境并导出依赖的实际案例

在项目开发中，为避免不同项目的依赖冲突，使用 Conda 创建隔离环境是最佳实践。首先通过命令创建独立环境：

# 创建名为 myproject 的新环境，并安装 Python 3.9
conda create -n myproject python=3.9
# 激活该环境
conda activate myproject
# 安装常用数据科学包
conda install numpy pandas scikit-learn

上述命令中，-n 指定环境名称，python=3.9 锁定语言版本，确保环境一致性。安装完成后，可导出当前环境的依赖配置：

# 导出环境依赖至 environment.yml
conda env export > environment.yml

该文件包含精确的包版本和通道信息，便于在其他机器重建相同环境。协作时，团队成员仅需执行 conda env create -f environment.yml 即可复现完整依赖。

依赖文件结构示例

第四章：进阶技巧与常见问题规避

4.1 如何排除开发依赖仅保留生产环境包

在构建生产级应用时，需确保部署环境中仅包含运行所需的依赖包，避免引入开发工具或测试库带来的安全与性能隐患。

使用 pipenv 精确导出生产依赖

通过 pipenv 可分离开发与生产依赖。执行以下命令生成仅含生产包的 requirements.txt：

pipenv requirements --deploy --strip-comments > requirements.txt

该命令仅导出 Pipfile 中 [packages] 部分的依赖，忽略 [dev-packages]，确保生产环境纯净。

验证依赖清单差异

可借助如下表格对比不同导出方式的结果：

4.2 处理版本冲突与精确控制依赖版本号

在现代软件开发中，依赖管理是确保项目稳定性的关键环节。当多个库依赖同一组件的不同版本时，版本冲突便可能发生。

锁定依赖版本

在 Python 中，使用 requirements.txt 中的 == 指令可明确指定版本：

django==5.0.2
requests==2.31.0

上述代码强制使用指定版本，避免间接依赖引入不兼容更新。通过语义化版本控制自动选择最小版本，确保构建可重现。

解决冲突的版本需求

当不同模块要求同一依赖的不兼容版本时，可通过 constraints.txt 统一版本路径：

-r requirements.txt
-django>=4.0,<5.0

该机制允许开发者手动干预版本选择，强制所有引用指向一个经过验证的版本，从而消除运行时行为不一致的风险。

4.3 自动生成带注释和分组的 requirements.txt 文件

在现代 Python 项目中，依赖管理不仅需要精确，还需具备可读性与可维护性。通过工具自动生成带有注释和逻辑分组的 requirements.txt 文件，能显著提升协作效率。

使用 pip-tools 实现依赖分组

通过 pip-compile 工具，可以从 requirements.in 生成锁定版本的依赖文件，并支持分组注释：

# requirements.in
# 主要依赖
django==5.0.*
djangorestframework

# 开发依赖
-r requirements-dev.in

# 部署依赖
gunicorn

上述结构允许将不同环境的依赖分离，提高可读性。

生成带注释的输出

执行 pip-compile --generate-hashes --output-file=requirements.txt requirements.in 后，生成的文件自动包含版本哈希与来源注释：

# This file is autogenerated by pip-compile
# To update, run: pip-compile --generate-hashes requirements.in
django==5.0.2 \
  --hash=sha256:... # via -r requirements.in

该机制确保依赖可复现且透明，适合团队协作与 CI/CD 集成。

4.4 requirements.txt 文件的编码与跨平台兼容性问题

在多平台协作开发中，requirements.txt 文件的编码格式和换行符差异可能引发依赖安装失败。默认情况下，Windows 使用 CP1252 或 GBK 编码保存文本文件，而 Linux 和 macOS 通常使用 UTF-8。若文件包含非 ASCII 字符（如注释中的中文），未统一编码将导致 pip install 报错。

推荐的编码规范

始终以 UTF-8 编码保存 requirements.txt，避免字符解析错误。可通过编辑器设置或命令行工具转换：

# 将文件转换为 UTF-8 编码
iconv -f GBK -t UTF-8 requirements.txt -o requirements_utf8.txt
mv requirements_utf8.txt requirements.txt

该命令将原 GBK 编码文件转为 UTF-8，确保跨平台一致性。

换行符与 Git 配置

不同操作系统使用不同的行结束符：Windows 用 CRLF，Unix-like 系统用 LF。通过 Git 管理时，建议设置：

• git config --global core.autocrlf input（Linux/macOS）
• git config --global core.autocrlf true（Windows）

确保提交时自动规范化换行符，防止因格式差异触发解析异常。

第五章：总结与高效依赖管理建议

制定清晰的版本控制策略

在多团队协作项目中，统一依赖版本至关重要。例如，某微服务架构项目因未锁定 grpcio 版本，导致不同服务间出现兼容性问题。通过引入 requirements.txt 显式指定版本可避免此类风险：

module myservice
go 1.21
require (
 google.golang.org/grpc v1.50.0
 github.com/gorilla/mux v1.8.0
)

注：此处原文混入了 Go 示例，建议在实际 Python 项目中直接使用 package_name==version 格式锁定版本。

定期执行依赖审计

使用工具自动化检测漏洞是保障安全的关键。建议每周运行一次依赖扫描，并集成至 CI 流程：

1. 执行 pip-audit 或 safety 检测已知漏洞
2. 导出报告并分配修复责任人
3. 更新至推荐的安全版本

某金融系统曾因未及时更新 jwt 库而暴露权限绕过风险，后续通过自动化流水线强制扫描阻断高危依赖。

构建私有模块代理缓存

为提升构建稳定性与速度，建议部署企业级模块代理。以下为性能对比数据：

流程图：依赖引入标准化流程
需求提出 → 安全评估 → 版本审批 → 代理缓存预加载 → CI 集成测试 → 生产发布