Python批量导出当前环境所有库及版本清单

图 0：Python 环境依赖包批量导出与清单生成全貌

一、导出前的关键前提：锁定正确的 Python 环境

很多初学者在执行导出命令时，常发现导出的清单与项目实际使用的包完全不符。这种情况绝大多数是因为终端当前调用的并不是项目专属的虚拟环境，而是系统的全局 Python 环境或另一个未关联的解释器。

在导出依赖清单前，必须通过路径确认当前处于预期的虚拟环境中：

• Linux / macOS 环境确认：执行 which python 与 which pip，输出路径应指向当前项目目录下的虚拟环境子目录（例如 /path/to/project/.venv/bin/python）。
• Windows 环境确认：在 PowerShell 或 CMD 中执行 where.exe python，优先显示的应为 .venv\Scripts\python.exe。

如果尚未激活项目虚拟环境，请先执行环境激活脚本：

# Linux / macOS 激活 venv 虚拟环境
source .venv/bin/activate

# Windows PowerShell 激活
.\.venv\Scripts\Activate.ps1

# Windows CMD 激活
.\.venv\Scriptsctivate.bat

图 1：Python 依赖清单批量导出标准四步流程

二、使用 pip freeze 导出标准依赖清单

pip freeze 是 Python 生态中最主流、兼容性最好的导出方式。该命令以 包名==精确版本号 的键值对形式输出，生成的内容可以直接供 pip install -r requirements.txt 解析与安装。

1. 导出标准 requirements.txt 命令

在确认虚拟环境激活后，运行下列重定向命令：

python -m pip freeze > requirements.txt

2. 导出的文件内容示例

导出的文本文件内容结构严谨，每行代表一个固定版本的依赖包（以下为示例输出）：

certifi==2024.7.4
charset-normalizer==3.3.2
idna==3.7
numpy==1.26.4
pandas==2.2.2
python-dateutil==2.9.0.post0
pytz==2024.1
requests==2.32.3
six==1.16.0
urllib3==2.2.2

3. pip freeze 的默认过滤机制与 --all 参数

pip freeze 在设计上专门针对依赖部署，因此它在默认情况下会自动过滤掉用于管理和构建的基础工具包：pip、setuptools、wheel 与 distribute。如果不希望过滤这些构建工具（例如需要做完全严格的环境镜像快照），可以追加 --all 参数：

python -m pip freeze --all > requirements.txt

图 2：pip freeze 与 pip list 核心机制及输出模式比对

三、使用 pip list 导出更丰富的可读报表

与专注于机器解析的 pip freeze 不同，pip list 默认用于人类阅读及包信息审计。在团队交付或环境巡检时，如果需要更灵活的格式（如 JSON 或表格），可以使用 pip list。

1. 查看与导出表格化清单

执行 python -m pip list 会输出对齐的二维列数据。通过重定向可以保存为文本清单供人工归档：

Package            Version
------------------ ---------
certifi            2024.7.4
charset-normalizer 3.3.2
Flask              3.0.3
pip                24.0
requests           2.32.3
setuptools         69.5.1

2. 导出为机器友好的 JSON 格式

当编写自动化运维脚本或 CI 流水线时，结构化的 JSON 数据便于通过脚本（如 Python、Node.js 或 jq）快速检索：

python -m pip list --format=json > installed_packages.json

导出的 JSON 文件内容形态（示例）：

[
  {"name": "Flask", "version": "3.0.3"},
  {"name": "requests", "version": "2.32.3"},
  {"name": "urllib3", "version": "2.2.2"}
]

3. 使用 freeze 兼容模式输出

pip list 也支持 --format=freeze 参数，其格式与 pip freeze 基本类似，但不会自动剔除 pip 与 setuptools：

python -m pip list --format=freeze > requirements.txt

四、Conda 环境下的依赖批量导出

在数据科学与人工智能项目中，Anaconda 或 Miniconda 极为常见。由于 Conda 不仅管理 Python 库，还管理底层 C/C++ 动态链接库（如 CUDA、OpenBLAS、MKL），因此其导出方式有两套对应方案。

1. 方案 A：纯 Python 依赖导出（生成 requirements.txt）

如果只需提取 Python 层的依赖并在纯 pip 环境中复现，可使用：

conda list --export > requirements.txt

2. 方案 B：完整环境定义导出（生成 environment.yml）

若需完整复制包括 Python 解释器版本、底层编译库和所有环境依赖在内的完整配置，推荐导出为 YAML 配置文件：

conda env export > environment.yml

图 3：依赖清单中的异常格式识别与清洗策略

五、依赖清单的检查、清洗与验证

批量导出完成后，不应直接提交到版本库或直接发送给同事。由于本地开发配置的特殊性，清单中常常混入不具备跨机器可移植性的条目，必须进行快速核查与清洗。

1. 剔除本地绝对路径（file:/// 协议）

如果曾经通过 pip install . 或本地源码包安装过库，pip freeze 可能会输出带有本地绝对路径的条目：

my-package @ file:///Users/developer/projects/my-package

这种格式在其他电脑或容器构建时必定因路径不存在而报错中断。修复方法：将其替换为公共或私有源的标准版本号（例如 my-package==1.0.0），或指向公司内部 Git 仓库链接。

2. 规范化可编辑开发包（-e git+...）

通过 pip install -e <url> 安装的开发包会生成 -e git+https://... 格式。在生产部署时，应确保指定了明确的分支或 Commit Hash，避免拉取到未经过测试的 master 分支最新代码：

# 明确绑定固定 release 标签或 commit hash
git+https://github.com/my-org/my-utils.git@v1.2.0#egg=my-utils

3. 清洗操作系统专属包

在 Ubuntu/Debian 上，如果误用系统 Python 环境运行了 freeze，常会出现 distro-info===0.23ubuntu1 或 python-apt 等带有三个等号（===）的特殊系统包。这些包在 Windows 或独立 Docker Alpine 镜像中无法通过 pip 安装，必须在文本文件中手动整行删除。

4. 仿真测试验证依赖可用性

在提交文件前，可以使用 pip 的 --dry-run 参数（pip 22.2+ 支持），在无需真正下载安装的情况下预先测试依赖解析是否合规：

python -m pip install -r requirements.txt --dry-run

若终端输出所有包的解析结果且没有版本冲突警告，即说明清单完全有效。

图 4：Python 依赖导出策略与复现路径决策总结

六、常见问题解答与适用边界

Q1：pip freeze 导出的包太多，很多不是我直接引用的，正常吗？

这是完全正常的。pip freeze 的职责是环境精确复制，因此它会递归包含你显式安装的主包以及这些主包所依赖的所有间接底层库。例如你只安装了 requests，清单里还会同时出现 certifi、charset-normalizer、idna 和 urllib3。正是因为锁定了这些底层库的具体版本，才能确保任何人在任何时间重建环境时都不会发生因依赖项自动升级而导致的代码崩溃。

Q2：如果只想导出当前项目代码实际 import 的包，该怎么做？

需要明确区分两类需求：

• 全量环境复现：使用本文讲解的 python -m pip freeze > requirements.txt。
• 按源码引用过滤：如果你在一个庞大的混用环境中写代码，只想扫描某个目录下的 .py 文件引用了哪些包，应使用第三方静态代码分析工具 pipreqs（命令为 pipreqs ./ --encoding=utf8 --force）。但对于正式的生产交付，优先推荐在专用的空虚拟环境中安装依赖并使用 pip freeze 导出。

Q3：如何在全新机器上一键恢复导出的依赖？

在拿到 requirements.txt 后，目标机器只需创建并进入新的虚拟环境，随后执行：

python -m pip install -r requirements.txt

如果在中国大陆地区下载较慢，可临时追加镜像源加速安装：

python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple