没有网络怎么安装Python库？离线安装whl和tar.gz包教程

图 0：Python 离线部署架构与中转流向总览

一、离线安装核心逻辑与四步操作闭环

许多初学者在离线主机上安装 Python 库时，常常直接从网上随意下载一个单体包，拷贝后执行安装，结果被接二连三的依赖缺失或架构冲突报错困扰。要确保离线安装一次性成功，必须遵循标准化的四步闭环流程。

图 1：Python 库离线安装的标准四步工程闭环

整个闭环涵盖四个关键阶段：

1. 第一步：探测目标机环境参数。不同操作系统平台（Windows、Linux、macOS）、不同 CPU 架构（x86_64、ARM64）以及不同 Python 解释器版本（如 Python 3.9、3.10、3.11）所适配的二进制库完全不同。必须先明确目标机器的底层参数，绝不能凭主观猜测下载。
2. 第二步：在联网机上执行精准下载。利用联网主机的 pip download 工具，不仅下载目标库本身，更要由包管理器自动递归解析并下载其层层关联的所有底层依赖包，汇聚为一个离线安装包目录。
3. 第三步：安全物理中转与校验。将整套离线包压缩归档（例如打包为 .zip 或 .tar.gz），通过 U 盘、移动硬盘或经过安全审计的内网跳板机传入隔离网，并在目标机上解压，核对文件数量与完整性。
4. 第四步：隔离机免网装载与环境验证。在目标机上使用 --no-index 与 --find-links 选项进行本地装载，彻底切断对外网源的隐式访问，并在 Python 交互终端中执行模块导入测试。

二、核心格式对比：.whl 预编译包与 .tar.gz 源码包的区别

在 PyPI（Python Package Index）上下载离线包时，最常见的两种文件扩展名是 .whl 和 .tar.gz。理解它们的本质差异是决定离线安装成败的关键。

图 2：Wheel (.whl) 预编译包与源码包 (.tar.gz) 核心机制与选型对比

1. 深入看懂 .whl 的命名规范（Wheel Tag）

Wheel 文件的名字包含了丰富的环境约束信息。例如：

numpy-1.24.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

该文件名依次由五个部分构成：

• numpy：库的分发名称。
• 1.24.3：该库的具体版本号。
• cp310：Python 解释器实现与大版本，此处代表 CPython 3.10。如果是 py3 或 py2.py3 则代表纯 Python 代码、不限具体 CPython 版本。
• cp310：ABI（应用程序二进制接口）标记。
• manylinux_..._x86_64：适用的操作系统与 CPU 硬件架构，表示适用于兼容常见 Linux 发行版的 64 位 x86 系统。

python -m pip debug --verbose

三、方法一：单个离线包的安装操作（基础用法）

当只需要安装某个极其轻量、没有任何额外外部依赖项的纯工具库时，可以使用单文件直接安装方式。

1. 单个 .whl 文件的离线安装

将下载好的 .whl 文件拷贝到目标机（例如放置在 /home/user/packages/ 或 Windows 的 D:\packages\ 下）。在命令行进入该目录，或者直接指定绝对路径：

# 示例：进入放置文件的目录后直接指定文件名
cd /home/user/packages
pip install numpy-1.24.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

# 也可以直接传入文件的完整路径
pip install "D:\packages
equests-2.31.0-py3-none-any.whl"

执行结果确认：终端若显示 Processing ./...whl 并最终输出 Successfully installed ...，即代表该轮子包已直接解压写入当前 Python 的 site-packages 目录。

2. 单个 .tar.gz 源码包的离线安装

源码包的安装有两种等效路径：

方式 A：直接通过 pip 安装归档文件（推荐）

pip install requests-2.31.0.tar.gz

pip 会在后台系统临时目录中将该包解压，自动读取 pyproject.toml 或调用 setup.py 执行构建并安装。

方式 B：传统手动解压并执行 setup.py 安装

# 1. 解压源码归档包
tar -zxvf requests-2.31.0.tar.gz

# 2. 进入解压出来的项目源码目录
cd requests-2.31.0

# 3. 执行 Python 标准安装指令
python setup.py install

注意：现代 Python 打包标准（PEP 517/518）已逐步将 setup.py install 标记为过时，更提倡使用方式 A 由 pip 托管安装过程。

四、方法二：带依赖的完整离线安装方案（工业级推荐）

现实开发中，绝大多数 Python 库并非“孤岛”。以数据分析核心库 pandas 为例，它深度依赖 numpy、python-dateutil、pytz、tzdata 等。如果仅拷贝一个 pandas-xxx.whl，安装会立即因缺少依赖而中断。

图 3：依赖树完整归集与 --no-index 离线装载工作流机制

步骤 1：在联网机器上完整下载依赖（依赖归集）

在操作系统与目标机环境相仿的联网开发机上，使用 pip download 命令。

场景 A：下载单个指定库及其所有依赖项

# 创建一个专门存放依赖包的目录
mkdir -p ./offline_packages

# 递归下载 requests 及其依赖项（urllib3, idna, charset_normalizer, certifi 等）
pip download -d ./offline_packages requests

场景 B：根据项目 requirements.txt 批量下载整个环境依赖

# 联网机批量下载整个清单的所有依赖
pip download -r requirements.txt -d ./offline_packages

下载完成后，查看 ./offline_packages 目录，你会发现里面整整齐齐地存放了主库及其所有底层间接依赖的全部 .whl 文件。

步骤 2：将依赖包归档并传输至目标机

# 在联网端打成一个压缩包，方便传输
tar -czf offline_packages.tar.gz ./offline_packages

# 传输到目标机后解压
tar -xzf offline_packages.tar.gz

步骤 3：在离线目标机上执行免网安装

进入解压后的目录所在位置，执行以下安装命令：

# 安装单个库并指定从本地离线目录查找依赖
pip install --no-index --find-links=./offline_packages requests

# 或者根据 requirements.txt 一键批量恢复整个运行环境
pip install --no-index --find-links=./offline_packages -r requirements.txt

五、跨平台/跨版本离线下载高级技巧

很多团队常见的工作场景是：程序员使用的是 Windows 10/11 笔记本 或 macOS，而需要离线部署的目标服务器是 Linux CentOS / Ubuntu (x86_64)。

若在 Windows 下直接执行 pip download pandas，默认下载的将是 Windows 平台专属的 win_amd64.whl，拷贝到 Linux 服务器上必然报错。此时必须在联网机上利用 pip download 的跨平台下载参数。

# 在 Windows/macOS 上为 Linux x86_64 + Python 3.10 环境下载依赖
pip download     --only-binary=:all:     --platform manylinux2014_x86_64     --python-version 310     --implementation cp     --abi cp310     -d ./linux_pkgs     requests

六、离线安装四大高频报错根因与排查速查

在无外网状态下，由于无法临时在线搜索错误日志，遇到安装报错往往令人头疼。下图中总结了离线部署过程中最常出现的 4 种典型故障及应对动作。

图 4：离线安装四大高频报错根因排查与解决动作矩阵

1. 报错：is not a supported wheel on this platform

表现：执行 pip install xxx.whl 时系统直接抛出该异常并退出。
根因：轮子文件名中的平台标签与当前 Python 环境不匹配。例如下载的是 Python 3.9（cp39）的包，却尝试安装在 Python 3.10 环境中；或者下载了 32 位（win32）包试图运行在 64 位系统上。
排查与解决：

• 切勿试图通过“重命名 whl 文件名”来蒙混过关，这会破坏内部的元数据哈希校验。
• 在目标机运行 python -m pip debug --verbose，仔细比对输出的兼容标签列表，回到联网机重新下载完全符合标签的安装包。

2. 报错：error: Microsoft Visual C++ 14.0 or greater is required

表现：在 Windows 下离线安装 .tar.gz 源码包时，终端输出大量 C++ 编译警告，最终中断报错。
根因：该源码包包含 C/C++ 原生扩展代码，安装过程中需要现场编译成 .pyd 动态库，而离线机器上没有安装 Microsoft C++ 构建工具链。
排查与解决：

• 最佳做法：放弃 .tar.gz，在 PyPI 官方页面上寻找并下载该版本针对当前 Python 的 .whl 预编译轮子包。
• 备用做法：若该库是团队内部开发或仅提供源码包，需在联网机提前制作好 Wheel（通过 pip wheel . 命令），再将打好的 .whl 拷贝至内网机安装。

3. 报错：No matching distribution found for [package_name]

表现：执行安装时提示找不到某个次级依赖库（如 charset-normalizer）。
根因：在联网机下载时采用了“单个包直接下载”，漏掉了该库底层的级联依赖。
排查与解决：在联网机针对报错提示所缺失的单包执行 pip download -d ./packages [package_name]，将补全的依赖单独拷贝进离线机器的安装包目录，再次执行安装即可。

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

表现：明确指定了 --no-index，但 pip 依然提示找不到版本。
根因：--find-links 指定的文件路径拼写错误、路径中存在特殊字符，或者指定路径下没有目标包相兼容的版本。
排查与解决：检查 --find-links 后面跟的是否为有效存在的文件夹路径；建议优先使用绝对路径，例如 --find-links=/data/packages。

七、安装成功验证与操作总结

在离线机器上完成 pip install 之后，务必进行真正的功能导入验证，而不仅仅依赖安装成功的控制台提示。在命令行进入 Python 交互式解释器：

python
>>> import requests
>>> print(requests.__version__)
2.31.0
>>> import pandas as pd
>>> print(pd.__version__)
2.0.3

若所有模块均能正常 import 且准确输出版本号，没有任何关于 DLL load failed 或 ModuleNotFoundError 的报错，即标志着本次离线安装彻底大功告成。