Python离线怎么安装包？手动安装whl和tar.gz文件教程

一、离线安装的前提：明确目标环境规格

离线安装并非简单地“把文件拖过来双击”。Python 包的分发格式（尤其是已编译的二进制 Wheel 包）与运行环境的平台、系统架构以及 Python 解释器版本强绑定。如果目标机与下载包的主机环境不一致，极易遭遇格式不兼容的报错。

在准备离线包之前，必须在无网络的物理目标机上，打开终端或命令行，获取以下三项核心参数：

• Python 主次版本号：例如 Python 3.10、3.11 或 3.12，直接对应标签中的 cp310、cp311。
• 操作系统与内核类型：例如 Windows、Linux（glibc 或 musl/Alpine）、macOS。
• CPU 硬件架构：例如 x86_64（AMD64）或 aarch64（ARM64）。

在目标机上运行以下两行命令，即可精确输出当前环境支持的 Wheel 兼容标签：

python -c "import packaging.tags as t; print(list(t.sys_tags())[:3])"

[<cp310-cp310-manylinux_2_17_x86_64>, <cp310-cp310-manylinux2014_x86_64>, <cp310-cp310-linux_x86_64>]

若目标环境尚未安装 packaging 模块，也可通过原生 sys 和 platform 模块直接判定：

python -c "import sys, platform; print(f'Version: {sys.version_info.major}.{sys.version_info.minor} | OS: {platform.system()} | Arch: {platform.machine()}')"

Version: 3.10 | OS: Linux | Arch: x86_64

二、在联网机上下载完整的离线文件

离线安装中最常见的问题并非命令输入错误，而是“依赖缺失”。例如安装 requests 时，它底层还依赖 urllib3、certifi、charset_normalizer 和 idna。若只拷贝单个 requests.whl，安装必然中断。

方法 1：使用 pip download 递归下载全部依赖（推荐）

在与目标环境同架构、同 Python 版本的有网络机器上，使用 pip download 命令，可以将目标包及其所有间接依赖一次性打包下载至指定目录：

# 创建存放离线包的独立目录
mkdir -p /data/python_packages

# 下载 requests 及其全部依赖至该目录
pip download requests -d /data/python_packages

Saved /data/python_packages/requests-2.31.0-py3-none-any.whl
Saved /data/python_packages/urllib3-2.0.4-py3-none-any.whl
Saved /data/python_packages/certifi-2023.7.22-py3-none-any.whl
Saved /data/python_packages/charset_normalizer-3.2.0-cp310-cp310-manylinux_2_17_x86_64.whl
Saved /data/python_packages/idna-3.4-py3-none-any.whl
Successfully downloaded requests urllib3 certifi charset-normalizer idna

方法 2：在 PyPI 官网手动下载单个文件

访问 Python 官方索引库 pypi.org，搜索目标包后点击左侧的 Download files：

• 优先下载 .whl 文件：查找与目标环境匹配的标签（如 cp310-manylinux... 或 py3-none-any.whl）。
• 次选 .tar.gz 文件：列表最下方的 Source Distribution（源码分发），在无对应二进制轮子时使用。

三、手动安装 .whl 文件（Wheel）

.whl（Wheel）是 Python 官方推荐的构建格式。它的本质是一个经过标准化封装的 ZIP 压缩包，内部包含已经转换好的 Python 文件及预编译好的 C 扩展动态链接库（.so / .pyd）。安装 Wheel 包无需调用编译器，直接解压复制即可，因而速度极快且极少出错。

1. 单个包手动安装语法

在离线机器上，切换到放置文件的路径，或直接传入完整相对/绝对路径：

# 语法：pip install 文件名.whl
pip install urllib3-2.0.4-py3-none-any.whl

Processing ./urllib3-2.0.4-py3-none-any.whl
Installing collected packages: urllib3
Successfully installed urllib3-2.0.4

2. 多依赖安装方式

当存在多个依赖包时，有两种处理方案：

• 方案一（单步顺序安装）：依据依赖拓扑自底向上安装。例如 requests 依赖 urllib3 和 idna，则先依次安装 urllib3.whl、idna.whl，最后安装 requests.whl。若顺序颠倒，pip 会因离线找不到上游包而抛出错误。
• 方案二（一次性目录索引，强烈推荐）：让 pip 直接从本地离线目录中自动检索所有依赖关系，同时加上 --no-index 参数禁止访问外网，彻底避免请求超时：

# 核心参数：--no-index（不访问网络） --find-links（从指定本地目录找包）
pip install --no-index --find-links=/data/python_packages requests

Looking in links: /data/python_packages
Processing /data/python_packages/requests-2.31.0-py3-none-any.whl
Processing /data/python_packages/certifi-2023.7.22-py3-none-any.whl
Processing /data/python_packages/charset_normalizer-3.2.0-cp310-cp310-manylinux_2_17_x86_64.whl
Processing /data/python_packages/idna-3.4-py3-none-any.whl
Processing /data/python_packages/urllib3-2.0.4-py3-none-any.whl
Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests
Successfully installed certifi-2023.7.22 charset-normalizer-3.2.0 idna-3.4 requests-2.31.0 urllib3-2.0.4

四、手动安装 .tar.gz 源码包（Source Distribution）

.tar.gz（通常称为 sdist 源码包）是原始 Python 代码与构建配置文件的打包归档。相比直接包含二进制文件的 Wheel，安装源码包在离线环境下有更多前置约束。

1. 方式一：直接使用 pip 安装（推荐）

即使是 .tar.gz，现代 pip 也支持直接将其打包构建并安装：

# 基础安装命令
pip install PyMySQL-1.1.0.tar.gz

# 离线环境严防构建隔离联网：增加 --no-build-isolation 参数
pip install --no-build-isolation PyMySQL-1.1.0.tar.gz

Processing ./PyMySQL-1.1.0.tar.gz
  Preparing metadata (setup.py) ... done
Building wheels for collected packages: PyMySQL
  Building wheel for PyMySQL (setup.py) ... done
  Created wheel for PyMySQL: filename=PyMySQL-1.1.0-py3-none-any.whl size=44120 sha256=...
Installing collected packages: PyMySQL
Successfully installed PyMySQL-1.1.0

2. 方式二：解压后通过 setup.py 手动构建与安装

如果在极老的系统或 pip 本身损坏的环境中，可以回归最底层的 Python 安装方式：

# 1. 解压 tar.gz 压缩包
tar -zxvf PyMySQL-1.1.0.tar.gz

# 2. 进入解压后的源码目录
cd PyMySQL-1.1.0

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

running install
running build
running build_py
creating build/lib/pymysql
copying pymysql/__init__.py -> build/lib/pymysql
...
Finished processing dependencies for PyMySQL==1.1.0

五、常见报错与精准排查方案

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

表现：执行 pip install xxx.whl 时，终端提示该包在当前平台上不受支持。

原因：下载的 .whl 文件标签与当前 Python 版本、操作系统或架构不匹配。例如将适用于 32 位系统的包安装在 64 位系统上，或将针对 Python 3.9 编译的二进制包安装在 Python 3.10 环境中。

解决办法：在离线机上运行第一节介绍的 list(packaging.tags.sys_tags())，对照文件名中的 cpXXX 和系统标识，重新在联网机下载标签一致的文件。

2. 报错：No matching distribution found（尝试联网导致超时）

表现：明明指定了本地的单个安装包，pip 却卡住数十秒，最终输出超时并提示找不到依赖。

原因：目标包内部声明了其他依赖库，pip 试图连接官方索引查找上游包，但因机房无网络而超时断开。

解决办法：必须使用 --no-index 彻底切断联网尝试，并结合 --find-links 指定包含所有依赖文件的本地文件夹：

pip install --no-index --find-links=/path/to/local/packages package_name

3. 报错：error: command 'gcc' failed / Microsoft Visual C++ 14.0 is required

表现：在安装 .tar.gz 源码包时，控制台输出大量编译追踪信息，最终以编译命令失败告终。

原因：该源码包包含 C/C++ 扩展组件，离线系统缺乏对应的编译工具链（如 Linux 缺少 gcc/python3-dev，Windows 缺少 MSVC 构建环境）。

解决办法：不要在离线机上强行编译源码。回到联网机器上，专门为目标机架构寻找对应的 .whl 预编译轮子文件；或者在同版本的联网虚拟机中执行 pip wheel xxx.tar.gz 打包出 Wheel，再把生成的 .whl 复制到离线机安装。

六、离线安装最佳实践与全流程总结

为了在离线环境中实现高效率、可复现的 Python 依赖部署，规范化的工程操作通常分为三个标准阶段：

1. 导出需求清单：在开发机或测试环境中固化 requirements.txt，锁定全部包名与确切版本号。
2. 批量离线归档：在同构联网机上执行 pip download -r requirements.txt -d ./packages，打包成 .tar.gz 或 .zip 统一转运。
3. 闭环本地安装：在离线机解压后，执行 pip install --no-index --find-links=./packages -r requirements.txt 完成一键导入。