怎么基于requirements.txt批量下载Python离线安装包
本文详细讲解如何使用 pip download 命令基于 requirements.txt 文件批量下载 Python 离线安装包（Wheel 与源码包），涵盖准备依赖清单、同平台与跨平台下载、包目录结构验证及内网离线安装的完整操作步骤与注意事项。
在没有外网访问权限的服务器、内网测试集群或受限企业网络中部署 Python 项目时，通常无法直接执行 pip install 联网拉取依赖。解决这一问题的标准做法，是在有外网连接的环境中，利用 pip download 命令结合 requirements.txt 将项目所需的所有 Wheel 二进制包、源码包及间接依赖完整下载到本地文件夹，再通过物理介质或内部文件服务器将离线包拷贝到目标机器进行本地安装。
一、整体工作流与核心原理
批量下载离线包的核心在于让 pip 解析依赖图并保存安装包文件，而不是解压并安装到当前 Python 环境中。整个离线交付过程分为四个阶段：准备依赖清单、执行批量下载、核对包完整性与类型、传输并在内网目标机执行安装。
二、第一步：准备依赖清单 requirements.txt
在开始下载前，必须先获得清晰明确的依赖清单。通常有两种方式生成 requirements.txt：
- 方式 A（项目指定依赖）： 手动列出项目直接引用的核心包及其版本约束，例如
fastapi==0.110.0、uvicorn[standard]==0.29.0。pip download会自动计算并下载这些包所需的所有间接依赖。 - 方式 B（导出当前环境完整清单）： 在已经经过联调测试的开发或测试环境中，直接导出所有精确版本的包：
pip freeze > requirements.txt
假定准备好的 requirements.txt 内容如下：
requests==2.31.0 pandas==2.2.1 SQLAlchemy==2.0.28
三、第二步：同平台环境下的批量下载
如果下载包的机器与最终内网运行环境的操作系统架构（如 Linux x86_64）和 Python 小版本（如 Python 3.10）完全一致，批量下载最为直接，只需使用 -d（或 --dest）参数指定存放目录。
在有外网的机器上创建存放包的目录并执行下载：
# 创建用于存储离线包的目录 mkdir packages # 基于 requirements.txt 批量下载所有依赖包及递归子依赖到 packages 目录 pip download -r requirements.txt -d ./packages
下载过程中，pip 会输出类似如下的抓取信息（示例输出）：
Collecting requests==2.31.0 (from -r requirements.txt (line 1)) Downloading requests-2.31.0-py3-none-any.whl (62 kB) Collecting charset-normalizer<4,>=2 (from requests==2.31.0->-r requirements.txt (line 1)) Downloading charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (142 kB) Collecting idna<4,>=2.5 (from requests==2.31.0->-r requirements.txt (line 1)) Downloading idna-3.6-py3-none-any.whl (61 kB) Collecting urllib3<3,>=1.21.1 (from requests==2.31.0->-r requirements.txt (line 1)) Downloading urllib3-2.2.1-py3-none-any.whl (121 kB) Collecting certifi>=2017.4.17 (from requests==2.31.0->-r requirements.txt (line 1)) Downloading certifi-2024.2.2-py3-none-any.whl (163 kB) Successfully downloaded requests pandas SQLAlchemy certifi charset-normalizer idna urllib3 numpy python-dateutil pytz tzdata typing-extensions greenlet
requirements.txt 中只有 3 个直接依赖，pip 也会自动把它们底层依赖的 numpy、urllib3、certifi 等全部下载下来，确保内网安装时不会因缺少子依赖而报错。
四、第三步：跨平台或跨 Python 版本的参数化下载
许多开发者在 macOS（如 Apple Silicon M 芯片 / ARM64）或 Windows 工作站上办公，但目标内网服务器是 Linux（如 CentOS / Ubuntu x86_64）。如果直接执行简单的 pip download，pip 默认只会下载适配当前本地系统的二进制包，拷贝到 Linux 服务器后将无法安装。
针对跨平台场景，必须结合 --platform、--python-version、--implementation 以及 --only-binary=:all: 参数进行精确约束。
跨平台下载常用参数详解：
--platform：目标操作系统及架构体系，例如 Linux 常用manylinux2014_x86_64或manylinux_2_17_x86_64；Windows 64 位为win_amd64。--python-version：目标 Python 大小版本号，写为310（Python 3.10）或39（Python 3.9）。--implementation：Python 实现，CPython 标准解释器使用cp。--abi：应用二进制接口标识，例如cp310。--only-binary=:all:：非常关键的选项。因为跨平台时本地无法为目标系统编译 C/C++ 源码，因此必须强制只拉取编译好的.whl二进制包。
五、第四步：解析与核验下载的文件
下载完成后，切勿直接打包传输，应先查看 packages 目录下的文件命名与包格式。Python 离线包通常分为两种结构形态：
在本地终端执行 ls packages/ 查看目录内容：
certifi-2024.2.2-py3-none-any.whl charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.whl idna-3.6-py3-none-any.whl numpy-1.26.4-cp310-cp310-manylinux_2_17_x86_64.whl pandas-2.2.1-cp310-cp310-manylinux_2_17_x86_64.whl python_dateutil-2.9.0.post0-py2.py3-none-any.whl pytz-2024.1-py2.py3-none-any.whl requests-2.31.0-py3-none-any.whl SQLAlchemy-2.0.28-cp310-cp310-manylinux_2_17_x86_64.whl typing_extensions-4.10.0-py3-none-any.whl urllib3-2.2.1-py3-none-any.whl
六、第五步：内网离线安装验证与完整闭环
将 requirements.txt 以及下载好的 packages 文件夹打包并通过介质拷贝到内网离线服务器上，解压到例如 /opt/project/ 目录下。
在内网服务器的目标环境中，运行如下命令进行离线批量安装：
# 进入包含 packages 和 requirements.txt 的项目目录 cd /opt/project # 离线执行安装 pip install --no-index --find-links=./packages -r requirements.txt
关键参数说明：
--no-index：完全忽略 PyPI 默认源，禁止发起任何网络 HTTP 请求。若缺包会立即提示未找到，绝不会发生联网超时卡顿。--find-links=./packages：指定从本地某个目录（或 HTML 文件）中寻找符合版本的.whl或.tar.gz包文件。-r requirements.txt：按照清单定义的依赖关系进行安装，pip 会在本地目录中完成依赖解析与装载。
七、核心要点总结与排错对照表
为了保障基于 requirements.txt 批量下载及安装过程万无一失，下表总结了最容易遇到的异常情况及对应处理方案：
只要严格按照“相同平台配置下载”或“精确指定跨平台参数”，配合 pip download -r requirements.txt -d <目录> 与 pip install --no-index --find-links=<目录> -r requirements.txt，即可在完全脱网的隔离生产环境中稳定、高速完成依赖部署。
免责声明：本文内容仅供参考，不代表本站观点。转载或引用请注明出处。
