批量导出Python项目所有依赖包及其版本

温以宁

发布时间：2026-10-20| 4人浏览过

原创

在Python开发与团队协作中，为了让项目能够平稳迁移到测试服务器、生产容器或新成员的开发电脑中，我们需要将当前项目所使用的第三方模块及其准确版本清单完整导出为一个标准清单文件（通常命名为 requirements.txt）。这样其他环境只需一条安装命令就能完成依赖复现。批量导出依赖主要有两种经典路径：一是面向独立虚拟环境的环境全量快照，二是面向项目代码的静态导入扫描。本文将系统梳理两种方案的执行步骤、核心差异及验证方式。

批量导出Python项目所有依赖包及其版本 — 图 1：从环境状态判定到依赖验证的完整操作步骤

一、方法一：使用 pip freeze 导出环境全量依赖

pip freeze 是 Python 官方包管理器 pip 自带的原生命令。它的工作原理非常直接：读取当前 Python 运行环境的包安装记录（即 site-packages 目录下的分发元数据），将已安装的包名称和精准版本以 package==version 的标准格式输出。

1. 标准执行步骤

打开终端并激活当前项目专用的虚拟环境，确保命令行指示符前已带有虚拟环境名称标识（例如 (venv)）。接着切换至项目根目录，运行如下命令：

# 激活虚拟环境（以 macOS / Linux 为例）
source venv/bin/activate

# 若为 Windows 系统：
# .\venv\Scripts\activate

# 执行全量依赖导出并重定向保存为 requirements.txt
pip freeze > requirements.txt

执行完成后，项目根目录便会生成一个名为 requirements.txt 的纯文本文件。其内容示例如下：

Flask==3.0.3
Jinja2==3.1.4
MarkupSafe==2.1.5
Werkzeug==3.0.3
click==8.1.7
requests==2.32.3
urllib3==2.2.2

2. 适用边界与常见陷阱

pip freeze 的优点是执行速度极快、无需额外安装第三方扫描工具，且能够百分之百记录运行环境中的底层子依赖（间接依赖）。然而，它存在一个关键前提：当前运行环境必须是为该项目专门建立的独立虚拟环境。

重要注意：避免在系统全局环境中直接运行 pip freeze

如果在全局 Python 环境（如操作系统直接安装的 Python）中执行 pip freeze，系统会把机器上安装过的所有调试工具、Jupyter 笔记本、系统级依赖（甚至包含操作系统绑定的特殊包）一并导出。这会导致导出的依赖列表极其臃肿，且在其他操作系统上执行安装时极易因平台不兼容而报错中断。

二、方法二：使用 pipreqs 基于源码扫描精准导出

如果项目没有建立专属虚拟环境，或者环境中安装了大量开发期间遗留的临时实验包，此时使用 pip freeze 就会把无关包全部打包进去。针对这种情况，更稳健的做法是使用 pipreqs。它通过对项目代码树进行 AST（抽象语法树）解析，只提取代码中实际出现的 import 和 from ... import 模块，并从 PyPI 或当前环境检索对应版本，从而输出干净、纯粹的项目依赖清单。

1. pipreqs 的安装与标准用法

首先在当前开发环境中安装 pipreqs 工具：

# 安装扫描工具
pip install pipreqs

进入项目所在根目录，运行扫描命令。在包含中文注释的代码工程中，建议显式指定编码为 UTF-8：

# 扫描当前目录并导出依赖
pipreqs ./ --encoding=utf-8

如果当前目录下已经存在旧的 requirements.txt，默认情况下 pipreqs 会提示文件已存在并停止覆盖。若需强制覆盖旧文件，加上 --force 参数即可：

# 覆盖已存在的 requirements.txt 文件
pipreqs ./ --encoding=utf-8 --force

2. 忽略特定目录

大型项目通常包含测试缓存、本地虚拟环境目录（如 venv/、.venv/）或临时测试脚本。如果希望跳过特定目录，可以使用 --ignore 参数排除它们，防止将开发调试阶段的包带入生产清单：

# 忽略虚拟环境目录与自动化测试目录
pipreqs ./ --encoding=utf-8 --force --ignore .venv,tests

三、现代包管理工具的标准化导出（Poetry 与 PDM）

在基于 pyproject.toml 的现代工程体系中，项目通常依赖 Poetry、PDM 或 uv 等现代化管理工具。这类工具会将抽象依赖记录在配置文件中，并通过 lock 文件锁定所有子依赖的具体版本与 Hash 哈希值。如果需要向传统 pip 部署环境分发依赖，可以通过它们的原生命令快速导出标准的 requirements.txt。

1. Poetry 导出方式

如果项目使用 Poetry 管理，直接运行 poetry export 命令即可将锁定的依赖转换为标准格式：

# 导出生产环境必需依赖（不包含哈希校验值与开发测试包）
poetry export -f requirements.txt --output requirements.txt --without-hashes

# 若需要同时导出包含测试、代码风格等开发依赖（dev 组）
poetry export -f requirements.txt --output requirements-dev.txt --with dev --without-hashes

2. PDM 导出方式

在采用 PDM 的项目中，执行 pdm export 可以实现相同效果：

# 导出生产环境依赖至 requirements.txt
pdm export -f requirements --output requirements.txt --without-hashes

四、导出文件的验证与异常项排查

批量导出完成后，不应直接将生成的文本提交并投产。建议花一分钟完成自检，排查以下几类在实际开发中极其常见的异常记录：

异常现象 / 记录模式	产生根源	解决方法
`package @ file:///...`	以本地可编辑模式（`pip install -e .`）或本地路径安装了包，记录了本机绝对路径	改为常规版本号 `package==x.y.z`，或在部署时配合私有仓库/打包分发
`pywin32==306`	Windows 特有的操作系统底层接口包，直接进入了全量导出	在非 Windows 系统（如 Linux 服务器）上安装会直接报错，建议手动移除或加上环境标记 `; sys_platform == 'win32'`
中文路径或字符报错 `UnicodeDecodeError`	扫描工具读取包含中文注释的源码文件时采用了系统默认的 ASCII 或 GBK 编码	在命令中显式加入 `--encoding=utf-8` 参数
动态引入的插件包丢失	使用 `__import__()` 或 `importlib` 动态加载的包无法被静态 AST 识别	在 requirements.txt 末尾手动追加该包名及具体版本

实战验证：在新环境中测试复现

验证导出的 requirements.txt 是否健康，最可靠的手段是在本地创建一个全新的临时测试环境：

# 1. 创建临时的独立测试虚拟环境
python -m venv test_env

# 2. 激活测试环境
source test_env/bin/activate
# Windows 为：.\test_env\Scripts\activate

# 3. 运行依赖安装
pip install -r requirements.txt

# 4. 执行项目入口脚本确认运行正常
python main.py

# 5. 验证完成后退出并清理临时测试环境
deactivate
rm -rf test_env

五、总结

批量导出 Python 项目的依赖包及其版本是保障软件可移植性与持续交付的基础环节。总结起来：

在已隔离的专属虚拟环境下，直接使用 pip freeze > requirements.txt 能够最完整地锁死当前所有依赖树；
在缺少虚拟环境或接手复杂旧代码时，使用 pipreqs ./ --encoding=utf-8 能够精准提取代码直接调用的模块，避免全局环境污染；
在现代团队项目中，优先使用 Poetry 或 PDM 等现代化工具进行锁定与标准导出；
文件生成后，务必检查是否存在本机绝对路径或特定平台的专属依赖，并通过在新虚拟环境中执行 pip install -r requirements.txt 完成最终的闭环验证。