无网环境怎么安装Python库？离线whl和tar.gz包安装教程

1. 核心认识：whl 与 tar.gz 安装包的本质区别

面对离线安装需求，很多读者遇到的第一道阻碍是“安装包明明拷进去了，但依然安装失败”。这通常与包的封装格式以及是否缺失下层编译环境直接相关。

Wheel 文件（.whl）：是 Python 官方推荐的二进制打包格式。它的本质是一个经过压缩的文件包，里面通常已经包含了针对特定操作系统、架构与 Python 解释器编译好的二进制代码和纯 Python 脚本。安装 .whl 文件时，pip 只需要执行解包和复制操作，不需要离线机器具备 C/C++ 编译器。因此，在离线环境中，只要平台架构与 Python 版本相匹配，安装 .whl 是最稳定、最高效的选择。

源码分发包（.tar.gz）：属于源码压缩包（sdist）。包内包含的是库的源代码及 setup.py 或 pyproject.toml 构建配置文件。纯 Python 编写的源码包可以直接运行构建脚本；但如果该库包含由 C、C++ 或 Rust 编写的底层拓展模块（例如早期或特定环境下的 NumPy、Cryptography 等），安装时 pip 必须在离线机器本地调用编译器进行即时编译构建。若离线机器未预装开发工具链，安装就会因缺少编译环境而中断。

2. 准备阶段：在联网机器下载包及其全部依赖

离线安装绝不能仅下载目标主包，因为现代 Python 库几乎都存在树状依赖链。例如安装 requests，它同时依赖 urllib3、certifi、charset_normalizer 和 idna。若只拷贝主包，离线安装时就会触发依赖缺失报错。

最规范的准备方式是利用 pip 提供的 download 指令。该指令只将文件与依赖下载到指定目录，并不在当前机器上安装。

2.1 同构环境下的依赖批量下载

如果联网机器与离线目标机的操作系统（如均为 Linux x86_64）、Python 小版本（如均为 Python 3.10）保持一致，可以直接下载：

# 创建存放离线包的文件夹
mkdir packages

# 下载单个库及其所有依赖
pip download requests -d ./packages/

# 或根据 requirements.txt 下载整套项目依赖
pip download -r requirements.txt -d ./packages/

2.2 跨平台、跨版本的精确下载参数

当联网开发机是 Windows/macOS，而离线生产机是 Linux 服务器时，直接执行普通 download 会下载与当前开发机匹配的包，导致传到 Linux 后无法识别。此时需要向 pip 显式指定目标平台、Python 版本及 ABI 规范：

# 针对 Linux x86_64、Python 3.10 环境跨平台下载 whl 依赖
pip download \
    --only-binary=:all: \
    --platform manylinux2014_x86_64 \
    --python-version 310 \
    --implementation cp \
    --abi cp310 \
    -d ./packages/ \
    requests

参数说明：--only-binary=:all: 强制只下载预编译的 wheel 包；--platform 指定目标系统架构标签；--python-version 与 --abi 锁定 Python 运行时版本（cp310 代表 CPython 3.10）。

3. 实战操作：在离线环境中安装 whl 文件

当包含所有 .whl 文件的目录传输到离线主机后（假设存放路径为 /opt/packages），即可在终端开展安装工作。

3.1 单个无依赖或轻量 whl 的直接安装

如果确认该库不依赖其他外部包，或相关依赖已提前安装完毕，可直接指向文件路径进行安装：

# 直接安装指定路径下的单个 whl
pip install --no-index /opt/packages/six-1.16.0-py2.py3-none-any.whl

关键参数 --no-index 表示告诉 pip“忽略 PyPI 远程索引，绝不要发起网络请求”。如果不加该参数，pip 在解析元数据时仍会默认尝试联网握手，从而导致长时间卡顿并报连接超时错误。

3.2 包含复杂依赖链的标准安装命令

对于包含多个依赖库的项目，切忌按主观顺序挨个手动敲命令安装。正确做法是利用 --find-links 参数，把本地存储目录作为一个临时的“私有静态文件源”，由 pip 自动在本地目录中完成依赖解析：

# 语法：指定本地目录作为搜寻源，安装目标库
pip install --no-index --find-links=/opt/packages/ requests

# 如果有 requirements.txt，可实现整套环境的一键离线还原
pip install --no-index --find-links=/opt/packages/ -r requirements.txt

4. 实战操作：在离线环境中安装 tar.gz 源码包

部分公司内部自研库、未经打包编译的历史模块或特定纯算法库可能仅以 .tar.gz 源码形式提供。针对这类文件，通常有两种离线安装途径。

4.1 方法一：使用 pip 直接指向 tar.gz（推荐）

现代版本的 pip 已经可以直接识别并安装本地源码包，同时支持在同一命令中结合 --find-links 自动补齐该源码包所需的其他依赖：

# pip 自动解压并调用构建工具，若依赖在 /opt/packages/ 中同样会自动安装
pip install --no-index --find-links=/opt/packages/ /opt/packages/demo_tool-1.0.0.tar.gz

如果提示构建隔离相关报错（PEP 517 build isolation 试图创建临时隔离环境下载构建依赖），可追加 --no-build-isolation 参数，强制 pip 使用当前环境中已有的 setuptools 和 wheel：

pip install --no-index --no-build-isolation --find-links=/opt/packages/ demo_tool-1.0.0.tar.gz

4.2 方法二：手动解压并执行 setup.py

在极其精简或较老的 Python 环境中，如果 pip 命令出现异常，可通过传统源码解包方式安装：

# 1. 解压源码归档
tar -zxvf demo_tool-1.0.0.tar.gz

# 2. 进入解压后的项目根目录
cd demo_tool-1.0.0

# 3. 执行安装脚本
python setup.py install

注意：通过 python setup.py install 安装的包不会自动解析并下载安装其依赖项。如果该包依赖其他第三方库，必须在执行此命令前，先在环境中把依赖库逐个安装完毕。

5. 验证安装结果

终端输出 Successfully installed 并不代表在所有运行场景下都能正常被业务调用。建议在当前解释器下执行导入验证与路径核对：

# 验证能否正常导入，并输出安装版本与具体落地文件路径
python -c "import requests; print('版本:', requests.__version__); print('路径:', requests.__file__)"

若无任何报错并正确打印出库的版本号和 site-packages 下的绝对物理路径，即表明离线安装完全成功。

6. 离线安装常见报错与排查决策树

在纯内网环境中，安装报错往往集中在三个典型场景：