没有网络时怎么离线安装 Python whl 或 tar.gz 包

离线安装 Python 包的核心逻辑是“外网预下依赖，内网定向直装”：在另一台能够联网的计算机上，使用 pip download 预先下载目标包及其全部依赖项保存为本地文件，通过移动存储介质转运至无网络机器后，再使用 pip install --no-index --find-links=<目录> 指定本地路径完成安装。针对 .whl（二进制轮子包）可直接复制解压安装，而针对 .tar.gz（源码包）则需保证目标系统具备相应的 C 编译工具链，或在下载时强制转为预编译的二进制 Wheel。

一、认识离线安装的核心对象与格式差异

在 Python 的分发体系中，我们最常接触到的离线安装包主要有两类：后缀为 .whl 的 Wheel 包和后缀为 .tar.gz（或 .zip）的源码包（Source Distribution，简称 sdist）。在无网络环境下，选择哪种格式直接决定了安装能否一次成功。

了解这个差异至关重要：许多人在内网安装诸如 numpy、pandas、cryptography 时，如果不小心下载了 .tar.gz 源码包，一执行安装就会因为离线机没有 GCC、make 或缺失 Python.h 头文件而直接中断，陷入必须先给离线机安装 C 编译器的二次困境。因此，在离线准备阶段，应尽可能强制下载目标环境的 .whl 包。

二、离线机器的前置环境摸底

在前往联网电脑下载安装包之前，必须先在离线机器上收集其基础环境指标。这是因为 .whl 文件名严格匹配特定环境标签，一旦下载错版本，离线机就会抛出 "is not a supported wheel on this platform"。

在离线机器的终端中执行以下两行基础探测命令：

python -c "import platform, sys; print(f'OS: {platform.system()} | Arch: {platform.machine()} | Python: {sys.version.split()[0]}')"
python -m pip debug --verbose

OS: Linux | Arch: x86_64 | Python: 3.10.12
Compatible tags: 32
  cp310-cp310-manylinux_2_35_x86_64
  cp310-cp310-manylinux_2_31_x86_64
  cp310-cp310-manylinux_2_28_x86_64
  ...
  py3-none-any

记录下输出中的三个核心要素：

• 操作系统与架构：例如 Linux x86_64、Linux aarch64，或 Windows AMD64。
• Python 主次版本：例如 Python 3.10（对应 cp310）、Python 3.8（对应 cp38）。
• 最高兼容标签：例如 manylinux_2_31_x86_64 或 win_amd64，它限定了所能安装的二进制 Wheel 的上限。

三、在联网电脑上准备离线安装包（核心步骤）

初学者最常犯的错误，是在浏览器里只下载了目标包一个单独的文件（例如只下载了 requests-2.31.0-py3-none-any.whl），到离线机上一装立即报错。这是因为几乎所有 Python 库都有下级依赖包（例如 requests 依赖 urllib3、certifi、charset_normalizer、idna）。

正确的做法是使用 pip 的 download 子命令，让 pip 在联网状态下递归计算并下载整棵依赖树。根据联网电脑与离线电脑的环境关系，可分为以下两种情况：

场景 A：联网电脑与离线电脑环境同构（最简单推荐）

如果两台机器安装了相同或兼容的操作系统（例如同为 Ubuntu 22.04 x86_64 且 Python 版本相同），直接在联网机建立一个空目录并执行：

mkdir -p offline_packages
pip download requests -d ./offline_packages/

# 如果有现成的 requirements.txt
pip download -r requirements.txt -d ./offline_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-cp310-cp310-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 ./offline_packages/requests-2.31.0-py3-none-any.whl
Saved ./offline_packages/charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.whl
Saved ./offline_packages/idna-3.7-py3-none-any.whl
Saved ./offline_packages/urllib3-2.2.1-py3-none-any.whl
Saved ./offline_packages/certifi-2024.2.2-py3-none-any.whl
Successfully downloaded requests charset-normalizer idna urllib3 certifi

此时可以看到，即使你只要求下载 requests，pip 也自动将 4 个底层依赖全部下载到了 ./offline_packages/ 目录下，形成了一个自包含的离线包集合。

场景 B：联网电脑与离线电脑环境异构（跨平台下载）

若你的联网办公电脑是 macOS (Apple Silicon M系列芯片) 或 Windows，而离线机器是一台 Linux x86_64 服务器，此时如果直接执行普通 download，下载的包往往是当前办公机平台的二进制，拷贝过去必然无法识别。

针对跨平台下载，必须向 pip 提供目标系统的具体规格参数，并且必须加上 --only-binary=:all: 参数：

pip download   --only-binary=:all:   --platform manylinux2014_x86_64   --python-version 310   --implementation cp   --abi cp310   -d ./offline_packages/   requests

四、在离线机器上执行安装

通过 U 盘、内部跳板机或局域网共享，将整个 offline_packages/ 目录完整拷贝到离线机器的本地磁盘（例如放在 /home/user/offline_packages/）。接下来就可以进行离线安装。

方式 1：目录级依赖自动装配（强烈推荐的标准命令）

不要一个个按顺序手动去装每个 whl 文件。正确的做法是在离线机器上运行带有 --no-index 和 --find-links 选项的 pip 命令：

pip install --no-index --find-links=/home/user/offline_packages/ requests

pip install --no-index --find-links=/home/user/offline_packages/ -r requirements.txt

Looking in links: /home/user/offline_packages/
Processing /home/user/offline_packages/requests-2.31.0-py3-none-any.whl
Processing /home/user/offline_packages/certifi-2024.2.2-py3-none-any.whl
Processing /home/user/offline_packages/charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.whl
Processing /home/user/offline_packages/idna-3.7-py3-none-any.whl
Processing /home/user/offline_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

这两项参数的作用非常明确：

• --no-index：命令 pip 完全忽略默认的 PyPI 官方网络索引服务器，严禁发起任何出站网络探测，防止无网导致长时间连接超时。
• --find-links=<目录路径>：将指定的本地文件夹作为唯一的候选包池。pip 会在该目录下自动分析依赖关系、计算拓扑排序，并按正确的先后顺序一气呵成完成安装。

方式 2：单个 .whl 文件直接安装

如果你安装的是一个本身没有任何第三方依赖的独立轮子（如部分工具包），或者其所有底层依赖已经在系统中提前装好，可以直接指向该文件路径：

pip install /home/user/offline_packages/simplejson-3.19.2-cp310-cp310-manylinux_2_5_x86_64.whl

方式 3：.tar.gz 源码包的离线安装

如果你拿到的安装包是源码分发格式（如 .tar.gz 或 .zip），离线安装有两种途径：

途径 3.1：通过 pip 离线直接安装源码包

现代版本的 pip 支持直接指向源码归档文件进行构建并安装：

pip install --no-index --find-links=/home/user/offline_packages/ /home/user/offline_packages/samplepkg-1.0.0.tar.gz

途径 3.2：传统手动解压源码安装

如果离线机器没有较新的 pip 或者 pip 本身损坏，可使用 Python 传统的构建脚本：

tar -zxvf samplepkg-1.0.0.tar.gz
cd samplepkg-1.0.0
python setup.py install

五、安装结果验证

不要仅凭终端最后一行提示就断定完全就绪，应当在离线终端中实际导入模块，并打印其版本号与具体加载的文件路径，以确认没有发生环境版本污染：

python -c "import requests; print('Version:', requests.__version__, '| Path:', requests.__file__)"

Version: 2.31.0 | Path: /usr/local/lib/python3.10/site-packages/requests/__init__.py

如果控制台顺利输出版本号和 site-packages 下的具体路径，说明该包及其底层支撑库均已准确就绪，可以正常供工程代码调用。

六、离线安装高频疑难排查

1. 报错：Could not find a version that satisfies the requirement ... (from versions: none)

现象与成因：这是离线安装最普遍的错误。虽然添加了 --no-index，但在指定的本地目录中找不到目标包或它所依赖的某一子模块。

处理步骤：阅读报错信息中究竟是哪个包没有满足要求。返回联网电脑，执行 pip download <报错包名> -d ./offline_packages/ 将遗漏的包补齐，再次通过物理介质考入后重试。

2. 报错：xxx.whl is not a supported wheel on this platform

现象与成因：轮子包的文件名命名包含五部分（格式为 distribution-version-python_tag-abi_tag-platform_tag.whl）。离线机器的 pip 拒绝安装不属于本机当前平台或 Python 架构的 Wheel。例如试图把 cp39 的包安装到 Python 3.10 上，或者把 win_amd64 的包安装到 Linux 上。

处理步骤：在离线机上运行 python -m pip debug --verbose 打印出系统支持的所有 Tag 列表。在联网机上下载时，严格对照离线机打印出的 Tag 进行包选择。

3. 报错：Failed to build installable wheels for xxx / error: command 'gcc' failed

现象与成因：目标包是 .tar.gz 源码包且含有 C/C++ 扩展代码，离线系统内没有安装 C 编译器（GCC），或者没有对应版本的 Python 头文件包（python3-dev）。

处理步骤：强烈建议回到联网机上，使用 pip download --only-binary=:all: 命令强行寻找官方编译好的 manylinux 版的 .whl 包；如果该库官方确实没有发布轮子，则需要提前在离线主机通过操作系统包管理器（如 dpkg -i 或 rpm -ivh）把 gcc、make、glibc-devel、python-devel 等离线套件补齐。

4. 极端场景：离线机连 pip 自身都没有安装怎么办？

现象与成因：部分极简或受限的 Linux 生产环境仅有裸机 python3，没有预装 pip 命令。

处理步骤：

1. 在联网电脑上下载官方引导脚本：curl -O https://bootstrap.pypa.io/get-pip.py。
2. 在联网机下载 pip 及其基础依赖 wheel：pip download pip setuptools wheel -d ./pip_setup/。
3. 将上述脚本和 pip_setup 目录拷贝至离线机。
4. 在离线机运行：python3 get-pip.py --no-index --find-links=./pip_setup/，即可离线初始化安装 pip 工具。

七、总结与最佳操作清单

在无网络环境下进行 Python 环境构建与扩展包安装，只要掌握了以下四步闭环法则，就能彻底避免无休止的报错往返：

• 第一步（基线勘测）：离线机先测 Python 版本、架构和 pip debug 标签。
• 第二步（整链抓取）：联网机用 pip download 递归拉取全部依赖，优先选二进制 .whl 轮子。
• 第三步（隔绝外网）：离线机执行安装务必带上 --no-index --find-links=<目录>，让 pip 自主在本地按序解析依赖。
• 第四步（终端验证）：使用单行 python -c "import ..." 测试关键模块路径，确认生效。