无法联网时怎么从国内镜像站下载 PyTorch whl 离线安装
在目标服务器无法连接外网的环境下,如何利用联网计算机从国内开源镜像站(如清华源、阿里源)下载适配的 PyTorch whl 安装包及其全量依赖,并通过离线方式成功安装与验证。
无法联网的环境部署 PyTorch,核心路径是“在具备外网环境的计算机上精确定位目标机器硬件与软件版本,借助国内开源镜像站高速下载对应的 wheel 安装包及全量关联依赖,最后通过移动介质转存至离线设备完成本地安装”。掌握这套方法能够避免因架构不匹配或缺包导致的离线安装中断。
第一步:采集目标离线主机的环境参数
下载离线安装包前,不能凭经验猜测目标机器的配置。PyTorch 预编译 wheel 包在文件名中固化了对 Python 解释器、操作系统内核版本、CPU 架构以及 GPU 计算平台的严格约束。如果下载的包与目标系统参数不匹配,安装时将直接抛出 is not a supported wheel on this platform 错误。
请登录到无法联网的目标主机,在终端中依次执行以下三项检测,记录对应的输出信息:
1. 确认 Python 版本与支持的 Tag 列表
在终端运行以下命令,获取 Python 版本号以及当前 pip 认可的平台兼容标签(Compatibility Tags):
python -V
python -c "import packaging.tags; print(list(packaging.tags.sys_tags())[:3])"
示例输出结果说明:
# 示例输出:
Python 3.10.12
[<cp310-cp310-manylinux_2_35_x86_64>, <cp310-cp310-manylinux_2_34_x86_64>, <cp310-cp310-manylinux_2_33_x86_64>]
由输出可知,目标机器的 Python 标签是 cp310,操作系统底层支持 manylinux 规范的 x86_64 架构。
2. 确认操作系统与 CPU 体系结构
通过系统工具确认内核架构:
uname -m && cat /etc/os-release
若返回 x86_64,表示为 64 位 Intel/AMD 架构;若返回 aarch64,表示为 64 位 ARM 架构。两者的二进制 wheel 文件不互通。
3. 确认显卡驱动与最大支持的 CUDA 版本
若机器搭载了 NVIDIA GPU 并希望启用 CUDA 加速,需执行:
nvidia-smi
在输出面板右上角,注意观察 CUDA Version: 12.2 或 CUDA Version: 11.8 等字段。该数值代表当前显卡驱动支持的最高 CUDA 运行库版本。下载 PyTorch 时选择的 CUDA 版本必须小于或等于该数值。如果是无显卡服务器或仅使用 CPU 运算,则统一选择 cpu 版本。
第二步:在联网机上利用国内镜像站下载离线包
PyTorch 的官方分发机制与普通 Python 第三方库有所区别:带有 CUDA 加速的大体积预编译二进制文件托管在专门的 download.pytorch.org/whl/ 仓库下,而非标准 PyPI 索引。国内各大高校与企业镜像站(如清华大学 TUNA、北京外国语大学等)对该 wheels 仓库进行了完整镜像,通常路径形如:
- 清华大学开源软件镜像站:
https://mirrors.tuna.tsinghua.edu.cn/pytorch-wheels/ - 北京外国语大学开源软件镜像站:
https://mirrors.bfsu.edu.cn/pytorch-wheels/
在可以正常联网的电脑上,可以通过两种方式下载安装包。优先推荐“方法一”,它能在单条命令中自动解析依赖图谱并打包所有前置库。
方法一:使用 pip download 命令全自动拉取依赖(推荐)
在联网机器的新建目录中执行以下命令。以目标机为“Linux x86_64、Python 3.10、CUDA 11.8”,需要安装 PyTorch 2.1.2 及其视觉工具包为例:
# 1. 建立存放下载包的专属目录
mkdir -p pytorch_offline_pkgs && cd pytorch_offline_pkgs
# 2. 执行跨端精准下载
pip download \
torch==2.1.2+cu118 \
torchvision==0.16.2+cu118 \
torchaudio==2.1.2+cu118 \
-f https://mirrors.tuna.tsinghua.edu.cn/pytorch-wheels/cu118/ \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
--dest . \
--platform manylinux2014_x86_64 \
--python-version 310 \
--implementation cp \
--abi cp310 \
--only-binary=:all:
-f .../cu118/:指定清华镜像站存放 CUDA 11.8 编译版本的寻找目录链接(Find-Links HTML)。-i .../simple:指定标准 Python 库镜像源,用于自动补齐 PyTorch 依赖的通用包(例如networkx、typing_extensions、sympy、jinja2等)。--dest .:将所有抓取到的.whl文件直接保存在当前目录。--platform manylinux2014_x86_64:强制指定目标操作系统为 Linux 64 位平台。即使当前联网机是 Windows 或 macOS,也不会下载错为本地系统格式。--python-version 310与--abi cp310:强制约束解释器版本为 Python 3.10。--only-binary=:all::禁止下载需要离线编译的.tar.gz源码包,全部强制拉取预编译好的二进制 wheel。
方法二:通过浏览器在镜像站网页索引直接手动下载
如果联网端没有 Python 或 pip 环境,可以直接通过浏览器访问清华镜像站的子版本目录:
https://mirrors.tuna.tsinghua.edu.cn/pytorch-wheels/cu118/
在该页面中使用浏览器的查找功能(快捷键 Ctrl+F 或 Command+F),根据第一步采集到的环境标记过滤文件:
- 主包:
torch-2.1.2%2Bcu118-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl - 视觉库:
torchvision-0.16.2%2Bcu118-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl - 音频库:
torchaudio-2.1.2%2Bcu118-cp310-cp310-manylinux_2_17_x86_64.whl
特别提醒:手动下载单包时,如果目标离线机是一个全新的 Python 干净环境,缺少 filelock、typing_extensions、sympy、networkx、jinja2 等基础包,直接安装上述 wheel 依然会报错。因此手动下载后,仍需在镜像源中将这几个基础依赖的 wheel 包一并下载下来。
第三步:拷贝至离线机器并校验文件完整性
将包含全部 .whl 文件的目录通过 U 盘、移动固态硬盘或内网安全中转通道拷贝到目标离线主机的存储路径下(例如 /home/user/pytorch_pkgs/)。
由于 PyTorch 的 CUDA 二进制包体积普遍在 2GB 到 3GB 之间,在大容量介质拷贝或网络跨区流转时极易发生微小的字节截断或损坏。如果文件不完整,解压校验会直接中断。建议在联网端与离线端分别执行哈希校验确认无误:
# 在 Linux 离线主机上校验文件大小与哈希
ls -lh /home/user/pytorch_pkgs/
sha256sum /home/user/pytorch_pkgs/torch-*.whl
第四步:在离线主机上执行本地安装
进入离线主机后,建议先激活准备好的独立虚拟环境(无论是 conda 还是 venv),避免污染系统基础环境。
# 激活虚拟环境示例(若使用 conda)
conda activate my_pytorch_env
在离线主机上安装时,千万不能直接执行 pip install torch,因为 pip 会默认尝试连接外网官方索引服务器导致超时。必须使用 --no-index 关闭网络连接,并使用 --find-links 指定本地目录:
# 进入包含所有下载好的 .whl 文件的目录
cd /home/user/pytorch_pkgs/
# 执行本地零联网离线安装
pip install --no-index --find-links=. torch torchvision torchaudio
命令执行机制解释:
--no-index:强制 pip 忽略远程索引仓库,绝不发出任何网络请求,不会出现因网络超时而卡顿或报错的现象。--find-links=.:告知 pip 在当前目录搜索所有匹配的 wheel 文件。pip 会自动在此目录中扫描torch及其所需要的所有依赖库(如typing_extensions、sympy等),自动规划依赖顺序并一次性完成安装。
第五步:离线环境的正确性验证
安装完成并不代表一定能调用 GPU 算力。必须在离线机器的 Python 交互终端中执行验证脚本,确认各项功能指标均已正常接入。
python -c "
import torch
print('PyTorch Version :', torch.__version__)
print('CUDA Available :', torch.cuda.is_available())
if torch.cuda.is_available():
print('Device Count :', torch.cuda.device_count())
print('Current Device :', torch.cuda.get_device_name(0))
# 执行一次简单的 GPU 张量加法运算,测试核函数调度
x = torch.ones(2, 3, device='cuda')
y = x + x
print('Tensor Computation: SUCCESS, sum =', y.sum().item())
else:
print('Running on CPU mode.')
"
正常执行的输出示例如下(具体显卡型号与版本号依机器而定):
# 正常输出示例:
PyTorch Version : 2.1.2+cu118
CUDA Available : True
Device Count : 1
Current Device : NVIDIA GeForce RTX 3090
Tensor Computation: SUCCESS, sum = 12.0
常见问题与应对方案
1. 报错:ERROR: ... is not a supported wheel on this platform
原因分析:下载的 wheel 包架构、Python 版本或 ABI 标签与当前主机环境不一致。例如为 Python 3.10 下载了 cp39 的包,或者为 Linux 下载了 win_amd64 的包。
解决方法:在离线机器上运行 pip debug --verbose,查阅输出列表中 Compatible tags 包含的全部合法标签,重新在联网端下载完全匹配该标签的 wheel 文件。
2. 报错:AssertionError: Torch not compiled with CUDA enabled
原因分析:下载安装的是 CPU 专用版本(文件名带有 +cpu),或者安装时不慎被清华源基础 simple 索引中未指定版本号的纯 CPU 预编译包覆盖。
解决方法:检查当前安装包文件名是否带有明确的 +cu118 或 +cu121 等 GPU 标记。卸载当前 torch 后,明确通过指定完整本地 wheel 路径重新进行安装。
3. 安装提示缺少 C++ 运行库(如 GLIBCXX_3.4.29 not found)
原因分析:高版本的 PyTorch 需要较新的 GCC C++ 运行时库支持,如果离线系统版本较老(如 CentOS 7),其系统自带的 libstdc++.so.6 无法提供所需符号。
解决方法:推荐使用 Conda 虚拟环境,Conda 环境内自带相对完整的现代化编译运行环境;或者在联网机上下载对应的新版 libstdc++.so 动态库并拷贝替换离线主机的软链接。
无网络环境下的核心原则是“事前精准摸底、全量解析下载、本地封闭安装”。善用 pip download 结合国内高校开源镜像站的 pytorch-wheels 目录,既解决了因跨境访问官方源速度缓慢或中断的问题,又一次性规避了繁琐的前置依赖缺失,是安全、规范、高效完成离线环境交付的实践途径。
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









