没有网络怎么离线安装Python第三方库

Dylan

发布时间：2026-11-03 | 4人浏览过

原创

针对无网络隔离环境下的Python第三方库安装需求，详细讲解依赖包下载、格式匹配、介质传输与离线安装的完整操作步骤与常见排错方法。

在涉密内网、机房隔离服务器或无网络接入的终端上，直接执行 pip install 会因为无法连接外网镜像源而报错终止。解决这一问题的标准操作路径是：在一台能联网的计算机上，使用 pip download 命令将目标库及其所有连带依赖项完整下载为本地 Wheel 安装包（.whl），通过 U 盘等介质拷贝到离线设备后，利用 pip install --no-index --find-links 指定本地目录完成安装。

一、离线安装的核心机制与关键条件

离线安装并不是简单地找一个 .whl 或 .tar.gz 源码包塞进目标机就可以运行。Python 第三方库通常具有复杂的依赖树。例如安装数据分析库 pandas 时，它要求系统中必须预先存在 numpy、pytz、dateutil 等多个基础库。如果离线机上缺少任一依赖，安装就会立刻中断。

因此，离线安装的根本任务在于完整收集依赖闭包，并确保下载的二进制包与目标机器的运行环境保持严格一致。在着手操作前，必须确认离线目标机器的三个关键基准：

操作系统与架构：确认是 Windows、Linux（如 CentOS、Ubuntu）还是 macOS，以及 CPU 架构是 x86_64（amd64）还是 aarch64（ARM64）。
Python 解释器大版本及 ABI：例如 Python 3.9、3.10 还是 3.11。二进制库的 Wheel 文件是强绑定 Python 内部 ABI（应用二进制接口）版本的。
环境内既有库状况：离线机是崭新的空环境，还是已经安装了部分底层库。如果无法确定，最稳妥的策略是下载全量依赖。

二、标准场景：相同环境下的离线部署流程

最简单且最稳定的离线场景，是联网计算机与离线计算机拥有相同的系统架构和 Python 版本（例如两台机器都是 64 位 Windows 且安装了 Python 3.10，或者都是 Ubuntu 22.04 LTS x86_64 搭配 Python 3.10）。此时只需 4 个步骤即可完成部署。

第 1 步：在联网机上下载安装包及其全部依赖

打开联网机器的命令行终端，创建一个专用于存放安装包的独立文件夹，使用 pip download 命令执行下载。例如我们需要安装 requests 库：

联网机命令终端

# 创建存放依赖包的目录
mkdir wheelhouse

# 下载 requests 及其全部依赖包到指定目录
pip download requests -d ./wheelhouse

如果需要一次性离线安装多个库，可以先整理一份 requirements.txt 文件，内容如下：

requests==2.31.0
pandas==2.2.1
openpyxl==3.1.2

然后执行批量下载：

pip download -r requirements.txt -d ./wheelhouse

示例输出

Collecting requests==2.31.0
  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.6-py3-none-any.whl (61 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 ./wheelhouse/requests-2.31.0-py3-none-any.whl
Saved ./wheelhouse/charset_normalizer-3.3.2-cp310-cp310-manylinux_2_17_x86_64.whl
...
Successfully downloaded requests charset-normalizer idna urllib3 certifi

第 2 步：检查并确认下载内容

进入 ./wheelhouse 目录，查看生成的文件列表。可以看到除了目标库本身，pip 自动将运行所需的次级依赖（如 certifi、urllib3、idna）全部一并下载为 .whl 格式文件。

第 3 步：将文件夹拷贝至离线计算机

将包含完整 .whl 文件的 wheelhouse 文件夹复制到移动存储设备，然后粘贴到离线计算机的一个固定路径下，例如 Linux 目标机的 /opt/wheelhouse，或 Windows 目标机的 D:\wheelhouse。

第 4 步：在离线机上执行安装

在离线机器的终端中，切换至包含目标 Python 环境的终端（若使用虚拟环境请先激活环境），运行带有 --no-index 与 --find-links 参数的安装命令：

离线机命令终端

# 单库安装
pip install --no-index --find-links=/opt/wheelhouse requests

# 或通过 requirements.txt 批量安装
pip install --no-index --find-links=/opt/wheelhouse -r requirements.txt

关键参数解析：

--no-index：强制要求 pip 忽略默认的包索引服务器（PyPI）。如果不加该参数，pip 在解析依赖时依然会尝试向外网发起 HTTP 请求，从而导致连接超时或直接报错失败。
--find-links=/opt/wheelhouse：告知 pip 在查找包时检索该本地目录，将该目录作为离线软件源。

三、进阶场景：跨平台与跨系统下载

现实工作中经常遇到软硬件环境不对等的情况：例如开发人员手头使用的是搭载 macOS（Apple Silicon 芯片）或 Windows 的笔记本电脑，而离线生产服务器是运行 Linux（CentOS / RHEL / Ubuntu x86_64）的机架设备。

如果直接在 macOS 上执行普通 pip download，pip 默认只会下载适配当前 macOS 平台的包文件。将其拷贝到 Linux 服务器上执行离线安装时，就会出现 is not a supported wheel on this platform（平台不受支持）错误。

针对此类跨平台下载需求，必须显式指定目标架构、Python ABI 与平台标识参数：

跨平台下载示例（在 macOS/Windows 上为 Linux x86_64 服务器下载）

pip download \
    --platform manylinux2014_x86_64 \
    --target-version 3.10 \
    --implementation cp \
    --only-binary=:all: \
    -d ./wheelhouse \
    pandas

参数解释：

--platform manylinux2014_x86_64：指定目标操作系统的二进制兼容规范（对于现代主流 Linux，通常采用 manylinux2014_x86_64 或 manylinux_2_17_x86_64；如果是 Windows 服务器则指定为 win_amd64）。
--target-version 3.10（或 --python-version 310）：明确目标环境的 Python 版本号。
--implementation cp：指定 Python 解释器实现为 CPython（即官方标准解释器）。
--only-binary=:all:：至关重要的约束参数。它要求 pip 仅下载已经编译就绪的二进制 .whl 文件，严禁下载 .tar.gz 源码包。因为离线服务器通常缺少 gcc、make 以及底层 C 开发头文件，源码包在离线环境下几乎一定会发生编译报错。

四、单文件 Wheel 的直接安装法

如果你明确知道要安装的库没有任何外部依赖（例如很多单纯的纯 Python 工具包，如 six、wheel、flit_core 等），或者该库所需的底层包已经在离线环境内预装齐备，则无需使用 --find-links 检索目录。

此时可以直接指定 .whl 文件的绝对路径或相对路径进行单文件安装：

单文件安装命令

# 直接安装指定路径下的单个 wheel 文件
pip install /path/to/wheelhouse/six-1.16.0-py2.py3-none-any.whl

如果该文件确实不存在其他缺失依赖，pip 会在数十毫秒内直接解压并写入 site-packages。但只要它暗含未满足的依赖项，该命令依然会立刻报错退出。

五、常见报错原因与排查修复

在离线安装过程中，最常遭遇的三类报错及其根本原因如下：

报错提示特征	根本原因	应对与解决策略
`Could not find a version that satisfies the requirement...`	离线目录下遗漏了某一层间接依赖包，pip 尝试联网获取但无法触达外网。	仔细阅读报错提示末尾指明的具体缺失包名及版本区间，在联网机重新使用 `pip download <缺失包名>` 下载并补齐至离线目录中。
`...is not a supported wheel on this platform`	Wheel 包的架构、Python 大版本或系统标签与目标机器实际环境不匹配。	检查 `.whl` 文件名中的标签（如 `cp39-cp39-win_amd64`）。若目标机是 Python 3.10，则必须重新下载 `cp310` 对应的 Wheel 文件。
`Failed building wheel for... / gcc: command not found`	下载到了 `.tar.gz` 源码包，安装时触发了 C/C++ 扩展编译，但离线机缺少编译套件。	联网下载时强制追加 `--only-binary=:all:` 参数，确保只拉取预先编译好的二进制 Wheel。

六、安装结果验证

完成安装后，必须进行两项确认以确保离线安装有效且可以正常加载：

使用 pip 查看元数据：执行 pip show <库名>，确认目标库的版本号、安装路径以及依赖关联均已正确登记。
执行 Python 导入测试：直接在命令行启动解释器导入该模块：
```
python -c "import requests; print(requests.__version__)"
```
若终端能够正确打印出预期的版本号（如 2.31.0）且没有任何警告或报错输出，说明该第三方库及其所有依赖已在离线环境中完全就绪，可以正式投入使用。