Python批量安装requirements.txt中的依赖库及导出方法

阿橙

发布时间：2026-11-13| 7人浏览过

原创

详细讲解Python项目中通过requirements.txt文件规范导出依赖库、批量还原安装的完整操作方法，涵盖pip freeze与pipreqs机制对比、国内镜像加速、离线安装及常见依赖冲突排错。

发布分类：Python 开发与部署实践环境标准：Python 3.8+ / pip 22.0+ 阅读时间：约 8 分钟

图 0：requirements.txt 依赖导出与跨端批量安装全景导图

在将本地调试完成的 Python 项目移交到测试服务器、Docker 镜像或新团队成员的开发电脑时，最常见的问题莫过于“本地运行正常，新机器逐个安装依赖不仅耗时繁琐，还经常因版本微小差异引发 ModuleNotFoundError 或运行时报错”。为了实现软件运行环境的确定性与可复现性，Python 官方推荐使用 requirements.txt 清单来固化和批量安装项目所需的第三方库。本文将围绕该清单的规范格式、依赖导出方案、批量安装策略以及常见故障诊断展开系统讲解。

一、什么是 requirements.txt 及其规范语法

requirements.txt 本质上是一个遵循特定语法的纯文本文件，记录了当前项目运行所依赖的所有第三方模块名称及其版本范围要求。当协同开发者或部署系统拿到该文件后，只需通过 pip 的 -r 参数即可一次性全自动拉取并安装全部依赖。

为了兼顾软件的稳定性与必要的升级灵活性，清单支持多种版本限定符。了解这些限定符的作用，有助于我们在编写和审查依赖清单时做到心中有数：

语法示例	限定类型	含义解释与适用场景
`requests == 2.31.0`	严格锁定 (Exact Match)	必须安装该具体版本。常用于生产部署，防止因底层库微调引入未知破坏。
`fastapi >= 0.100.0`	最低版本限制 (Minimum)	要求不低于 0.100.0 版本。常用于需要某些新特性的通用开发阶段。
`uvicorn ~= 0.24.0`	兼容性锁定 (Compatible)	等价于 `>= 0.24.0, == 0.24.*`，允许安装修复补丁，但拒绝破坏性大版本升级。
`pandas >= 1.5, < 2.0`	区间范围限制 (Range)	允许指定版本区间内的主版本更新，规避主版本升级带来的 API 弃用。
`-r base.txt`	文件递归引用 (Include)	引入另一个依赖清单文件。常用于将公共依赖 (base) 与生产依赖 (prod) 拆分管理。

语法注意：在 requirements.txt 中，以 # 开头的行为单行注释；可以直接在某行包名后添加注释说明用途。此外，如果某个依赖需要额外特性扩展包，可使用方括号语法（例如 uvicorn[standard]==0.24.0）。

图 1：Python 依赖清单从环境隔离导出到目标机批量安装的五步全景流程

二、Python 依赖清单的导出方法与适用场景

如何准确地将项目中正在使用的依赖库生成为 requirements.txt？社区中存在两种主流路径，它们的底层工作原理截然不同，选错方式往往会导致导出的文件臃肿不堪或丢失依赖。

方法一：使用 pip freeze 原生导出（推荐在独立虚拟环境中使用）

pip freeze 是 pip 工具自带的内置指令。它的运行机制非常直接：扫描当前 Python 运行环境中 site-packages 目录下物理安装的所有第三方包，按照 包名==精确版本号 的格式全量打印输出。

# 1. 确保已激活项目的虚拟环境（终端通常会出现环境名标识，如 (venv)）
# Linux / macOS
source venv/bin/activate
# Windows PowerShell
.\venv\Scripts\Activate.ps1

# 2. 将当前虚拟环境中安装的依赖重定向输出至 requirements.txt
pip freeze > requirements.txt

执行完成后，打开 requirements.txt，可以看到类似以下示例的内容：

certifi==2023.11.17
charset-normalizer==3.3.2
fastapi==0.104.1
idna==3.6
pydantic==2.5.2
pydantic_core==2.14.5
requests==2.31.0
starlette==0.27.0
typing_extensions==4.9.0
uvicorn==0.24.0.post1

重要警示：千万不要在未激活虚拟环境的“全局 Python 环境”下直接运行 pip freeze！如果你日常在全局环境中开发过其他项目、安装过 Jupyter、Flake8、爬虫工具等，全局 pip freeze 会把成百上千个与当前项目毫不相干的库一股脑写入清单，严重污染部署环境并造成安装体积膨胀。

方法二：使用 pipreqs 静态扫描导出（适用于未隔离环境或旧项目提取）

如果项目此前没有创建独立的虚拟环境，或者开发者直接混用了全局 Python，此时使用 pipreqs 更加合适。与 pip freeze 扫描物理磁盘包不同，pipreqs 通过静态分析当前项目目录中的全部 .py 源代码文件，检索所有 import 和 from ... import 语法树，仅提取当前项目实际引用到的依赖包。

# 1. 安装 pipreqs 工具
pip install pipreqs

# 2. 扫描当前项目目录并生成依赖清单
# --encoding=utf8 确保中文字符集正常解析，--force 允许覆盖已存在的清单
pipreqs ./ --encoding=utf8 --force

与 pip freeze 生成的结果相比，pipreqs 生成的清单更加纯粹干练，不会混入子依赖（如 certifi、idna）以及未使用的全局模块，非常适合用于给开源项目初次编写基础依赖清单。

图 2：pip freeze 与 pipreqs 的底层扫描机制与技术选型决策

清单导出后的必要审查与人工清洗

无论采用上述哪种方式生成文件，在提交给版本控制系统（如 Git）之前，都建议执行一次简短的人工审查：

清除本地绝对路径污染：有时使用 pip freeze 导出的清单中会包含类似 xxx @ file:///Users/... 的行，这是由于本地可编辑安装（pip install -e .）或非标准 wheel 包引起的。如果直接分发给其他机器，会因目标机不存在该绝对路径导致安装中断，必须将其删除或替换为官方标准包名。
剔除平台打包辅助包：例如 pywin32（仅适用于 Windows）或 wheel、distlib 等，若要跨操作系统部署到 Linux Docker，应将这类特定平台的非业务包做条件声明（例如 pywin32==306; sys_platform == 'win32'）或直接剥离。

三、批量安装 requirements.txt 中依赖库的核心方法

获取到规范的依赖清单后，在目标机器上批量安装非常快捷。根据目标环境的网络连通性与交付要求，主要有以下三种部署策略：

1. 基础批量安装与国内可信镜像加速

在有公网访问能力的目标服务器或本地环境，批量安装的标准指令为：

# 在目标机创建并激活全新的干净虚拟环境
python3 -m venv venv
source venv/bin/activate

# 执行基础批量安装
pip install -r requirements.txt

由于默认的官方 PyPI 服务器位于海外，直接拉取大型依赖库（如 torch、pandas 等）时容易出现网络缓慢或下载超时错误（ReadTimeoutError）。推荐在安装时指定国内优质镜像源进行下载加速：

# 使用清华大学开源软件镜像源批量安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 其他常用国内镜像源备选：
# 阿里云：https://mirrors.aliyun.com/pypi/simple/
# 腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/

持久化配置技巧：如果你不想每次执行命令都输入 -i 参数，可以在目标机器上运行一次 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple，将国内镜像源设置为全局默认配置。

图 3：pip 批量安装在公网镜像、内网离线与版本约束场景下的架构对比

2. 局域网与无外网生产环境的离线批量安装（Wheelhouse 模式）

在政企、金融或专有云等安全隔离网络中，生产服务器通常完全禁止连接公网。此时需要采用“联网机预打包 + 离线机本地安装”的模式：

# 【第一步：在有外网的相同架构开发机上】
# 将 requirements.txt 中所有包及其依赖的 .whl 二进制安装包统一下载到本地 wheels 目录
pip download -r requirements.txt -d ./wheels -i https://pypi.tuna.tsinghua.edu.cn/simple

# 【第二步：打包迁移】
# 将 requirements.txt 与 wheels 文件夹整体压缩打包并传输至离线服务器
tar -czvf project_deps.tar.gz requirements.txt wheels/

# 【第三步：在无外网的离线服务器上】
# 解压后，使用 --no-index 禁用外网查找，通过 --find-links 指定本地 wheel 包目录一键批量安装
pip install --no-index --find-links=./wheels -r requirements.txt

3. 增量更新与依赖升级参数

当项目需要更新已安装的依赖至清单声明的更高版本时，可以使用 -U（即 --upgrade）参数：

# 允许 pip 检查并将已安装的库升级至满足 requirements.txt 要求的最新可用版本
pip install --upgrade -r requirements.txt

四、批量安装常见报错与排错决策指南

在批量安装过程中，可能会遇到网络、环境工具链或包版本互斥带来的各种异常。按照以下思路排查可以快速解决绝大部分问题：

图 4：requirements.txt 批量安装异常诊断与修复决策树

1. 报错：Failed building wheel for xxx / error: command 'gcc' failed

表现：控制台打印红色报错，提示某个包（常见于 uwsgi、psycopg2、gevent、lxml 等底层包含 C 扩展的库）构建失败，缺少编译工具。

原因：PyPI 仓库中未提供适配当前操作系统架构的预编译二进制 Wheel 包，pip 只能下载源码压缩包并在本地实时编译，而目标机器缺少 C/C++ 编译器和 Python 开发头文件。

修复方法：

对于 Linux（Debian/Ubuntu），在系统层面安装编译基础链：sudo apt-get update && sudo apt-get install build-essential python3-dev；CentOS/RHEL 执行 sudo yum groupinstall "Development Tools" && sudo yum install python3-devel。
检查是否存在官方提供的二进制预编译版本包，例如将 psycopg2 替换为免本地编译的 psycopg2-binary。

2. 报错：ResolutionImpossible / VersionConflict（依赖版本冲突）

表现：pip 给出 ResolutionImpossible 提示，列出 Package A 需要 lib == 1.2.0，而 Package B 强制需要 lib >= 2.0.0，导致无解中断。

修复方法：

在终端运行诊断命令：pip check。pip 会直接指出当前环境中哪些包的依赖关系存在破坏。
打开 requirements.txt，将过紧的 == 硬编码版本放宽为 ~= 或 >=，允许依赖求解器找到双方都兼容的中间版本。

3. 报错：SSL: CERTIFICATE_VERIFY_FAILED 或 Connection timed out

表现：网络连接失败，提示无法验证 SSL 证书或连接已超时。

修复方法：如果在内网代理环境中自签证书被拦截，可以在使用国内镜像时显式信任主机名：

pip install -r requirements.txt -i http://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com

五、工程化规范总结

为了保障项目从开发、测试到生产交付过程中的环境一致性，建议在日常开发中贯彻以下最佳实践准则：

一项目一沙箱：坚持为每一个 Python 项目创建专用的虚拟环境（venv 或 conda），杜绝在全局 Python 环境下直接堆砌第三方库。
区分环境清单：大型项目中，可建立多份清单文件，例如基础运行依赖 requirements.txt、测试与代码格式化工具依赖 requirements-dev.txt，通过 -r requirements.txt 形成层级继承。
严格验收验证：每次在新机器执行 pip install -r requirements.txt 完毕后，随手执行一次 pip check。只要控制台回显 No broken requirements found.，即可证明所有依赖闭环健康，环境准备就绪。