Python离线安装模块：使用pip download与install的完整流程

山海之间

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

原创

详解在无外网隔离环境下使用pip download与pip install离线安装Python第三方模块与全部依赖的完整实操流程，涵盖同构及跨平台下载、Wheel预编译包匹配、离线批量安装与环境依赖校验。

在专网机房、保密开发环境或高安全级别的生产服务器上，主机通常完全断开公网连接。若要在这些机器上部署Python第三方模块，标准做法是在一台能够访问外网的机器上通过pip download命令解析并拉取目标模块及其全部依赖项的离线安装包（Wheel文件），随后将安装包传输至离线主机，最后借助pip install --no-index --find-links在本地完成完整安装。本文将详解这一流程的标准步骤、关键参数配置以及跨平台场景下的避坑要点。

Python离线安装模块：使用pip download与install的完整流程 — 图 1：Python 离线安装端到端架构与数据流向全景

一、离线安装的核心机制与准备工作

Python第三方库通常依赖大量次级包（例如安装 requests 时会自动依赖 urllib3、certifi、charset-normalizer 和 idna）。在联网环境中，pip install 会通过 PyPI 索引自动下载并逐一解析这些依赖；而在离线环境中，一旦缺少其中任何一个间接依赖包，安装进程就会立即中断并报出找不到分发包的错误。

因此，离线安装的核心在于依赖包的闭包收集：必须确保收集到的离线包集合在逻辑上是自洽且完备的。在开始执行命令前，需要明确两台机器的关键运行环境信息：

联网准备机（Online Machine）：拥有外网访问权限，安装有 pip 工具，用于下载轮子包。
离线目标机（Offline Machine）：无网络连接或无法访问 PyPI，运行实际的生产或开发任务。
三要素核对：操作系统类型（如 Linux CentOS/Ubuntu、Windows）、CPU架构（如 x86_64、aarch64）以及 Python 解释器的主次版本号（如 Python 3.9 与 3.10 对应的二进制 ABI 并不兼容）。

二、在联网环境下载离线安装包（pip download）

pip download 命令专门用于将模块及其所有底层依赖下载到指定目录，而不会将它们安装到当前联网机器的 Python 环境中。这有效避免了污染联网主机的开发环境。

1. 同构环境下的直接下载（联网机与离线机系统版本一致）

如果联网机器与离线主机的操作系统、系统架构和 Python 版本完全一致，下载操作最为直接。

单模块下载示例：

终端命令

# 创建存放离线包的专用目录
mkdir -p ./python_packages

# 下载 requests 模块及其所有依赖包到指定目录
pip download requests -d ./python_packages

示例输出

Collecting requests Downloading requests-2.31.0-py3-none-any.whl (62 kB) Collecting charset-normalizer<4,>=2 Downloading charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_x86_64.whl (142 kB) Collecting idna<4,>=2.5 Downloading idna-3.7-py3-none-any.whl (66 kB) Collecting urllib3<3,>=1.21.1 Downloading urllib3-2.2.1-py3-none-any.whl (121 kB) Collecting certifi>=2017.4.17 Downloading certifi-2024.2.2-py3-none-any.whl (163 kB) Saved ./python_packages/requests-2.31.0-py3-none-any.whl Saved ./python_packages/charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_x86_64.whl Saved ./python_packages/idna-3.7-py3-none-any.whl Saved ./python_packages/urllib3-2.2.1-py3-none-any.whl Saved ./python_packages/certifi-2024.2.2-py3-none-any.whl Successfully downloaded requests charset-normalizer idna urllib3 certifi

基于需求清单批量下载：

在实际工程中，通常需要安装一整套技术栈。可以先在项目根目录编写或导出 requirements.txt，然后执行批量拉取：

终端命令

# 批量拉取 requirements.txt 中声明的所有模块及其间接依赖
pip download -r requirements.txt -d ./python_packages

2. 跨平台/跨架构环境下载（异构环境配置）

很多工程师的工作机是 macOS 或 Windows，但目标离线服务器是 Linux（如 x86_64 的 CentOS 或 aarch64 的 EulerOS）。此时如果在工作机上直接执行 pip download，默认会下载适配工作机系统的安装包，传到离线服务器上将无法安装。

通过指定 --platform、--python-version 和 --only-binary=:all: 参数，可以在任意系统上精确下载适配目标环境的预编译包：

跨平台下载命令示例（在 Mac/Windows 上为 Linux x86_64 Python 3.9 收集包）

pip download   --platform manylinux2014_x86_64   --python-version 39   --implementation cp   --abi cp39   --only-binary=:all:   -r requirements.txt   -d ./python_packages

注意： 使用 --platform 参数时，必须同时带上 --only-binary=:all:。因为 pip 无法在跨平台模式下运行异构系统的 setup.py 脚本去分析源码包（.tar.gz）的依赖，必须强制要求下载已编译成二进制的 Wheel 格式。

三、离线数据包的转移与存储结构

下载完成后，./python_packages 目录中会存放一系列以 .whl（或个别纯 Python 源码包 .tar.gz）结尾的文件。为了保证传输效率与完整性，建议按如下方式操作：

将 requirements.txt 文件与下载的 python_packages/ 目录打包为压缩文件：
```
tar -czvf python_offline_bundle.tar.gz ./python_packages requirements.txt
```
通过 U 盘、移动硬盘或经过审批的内网文件传输跳板机（如 SCP/SFTP）将压缩包拷贝至离线主机的临时目录（例如 /tmp/offline_deploy/）。

在离线主机上解压归档包：

cd /tmp/offline_deploy
tar -xzvf python_offline_bundle.tar.gz

四、在离线目标机执行安装（pip install）

到达离线环境后，不能直接运行常规的 pip install package_name，因为 pip 的默认行为是向外网的 PyPI 发起 HTTPS 索引检索，在无外网环境下会导致漫长的超时卡顿并最终报错退出。

必须使用 --no-index 和 --find-links 两个核心选项：

--no-index：强制忽略包索引（即不连接互联网和远程源）。
--find-links=<url_or_dir>：指示 pip 在指定的本地文件目录中检索可用的离线分发包。

1. 离线安装单模块

终端命令

# 切换至离线主机解压目录
cd /tmp/offline_deploy

# 从本地目录安装 requests，pip 会自动在 ./python_packages 中查找其全部依赖包
pip install --no-index --find-links=./python_packages requests

示例输出

Looking in links: ./python_packages Processing ./python_packages/requests-2.31.0-py3-none-any.whl Processing ./python_packages/certifi-2024.2.2-py3-none-any.whl Processing ./python_packages/charset_normalizer-3.3.2-cp39-cp39-manylinux_2_17_x86_64.whl Processing ./python_packages/idna-3.7-py3-none-any.whl Processing ./python_packages/urllib3-2.2.1-py3-none-any.whl Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests Successfully installed certifi-2024.2.2 charset-normalizer-3.3.2 idna-3.7 requests-2.31.0 urllib3-2.2.1

2. 基于清单批量离线安装

若需要批量还原生产工程的所有依赖，配合 -r requirements.txt 执行：

终端命令

pip install --no-index --find-links=./python_packages -r requirements.txt

提示：在离线环境中也可以指定 --target=<directory> 参数将模块安装到自定义路径，或直接在已激活的 Python 虚拟环境（Virtualenv / Conda）中运行上述命令，安装包将被精准写入当前隔离环境的 site-packages 目录下。

五、安装后验证与排错指南

完成离线安装后，建议按以下三级验证法确认模块可用性及依赖链的健康度：

1. 依赖一致性检查

运行 pip check 可以自动扫描当前 Python 环境中的所有包，检查是否存在缺失依赖或版本不兼容的情况：

终端命令

pip check

预期正确输出示例

No broken requirements found.

2. 核心模块导入与调用测试

直接在命令行调用 Python 解释器导入刚刚安装的模块并打印版本号：

终端命令

python -c "import requests; print('requests version:', requests.__version__)"

示例输出

requests version: 2.31.0

3. 离线常见故障排查表

报错现象	根本原因	针对性解决方案
`ERROR: Could not find a version that satisfies the requirement...`	`--find-links` 指向的目录中遗漏了某个间接依赖包。	回到联网机，使用 `pip download <缺失的包名>` 补充拉取该模块对应版本的 Wheel 并再次传回。
`error: Microsoft Visual C++ 14.0 or greater is required` 或 `gcc: command not found`	下载时拉取到了包含 C/C++ 扩展的 `.tar.gz` 源码包，离线机缺少编译链。	在联网端下载时指定 `--only-binary=:all:`，强制获取预编译 `.whl` 文件，杜绝在离线机现场构建。
`is not a supported wheel on this platform`	下载的 Wheel 标签（系统架构、Python版本或 glibc版本）与离线机不匹配。	运行 `python -c "import packaging.tags; print(list(packaging.tags.sys_tags())[:3])"` 查询离线机支持的 tag，下载时对应指定。
命令一直卡住最终报网络连接超时 (Connection timeout)	未携带 `--no-index` 参数，pip 默认尝试连接外网仓库。	务必确认完整带上 `--no-index --find-links=<dir>` 参数。

六、工程实践中的推荐规范

为保证生产系统发布的高可靠性，在企业运维和开发工程中推荐落实以下三个习惯：

使用 pip-tools 或 pip freeze 固化版本：在生成 requirements.txt 时精确指定版本号（如 flask==2.3.3），防止不同时间下载拉取到不同版本的次级依赖导致兼容性差异。
离线安装包归档留存：将业务系统的代码版本与对应的 python_packages/ 依赖包归档存放在内部制品库或备份介质中，确保任何历史版本均可独立复现部署。
定期使用哈希校验：通过 pip download --require-hashes 生成带有 SHA256 哈希防篡改指纹的清单，进一步加固离线环境的软件供应链安全。