PyTorch离线安装实操指南：版本选型到依赖打包全流程

如果你在一台不能连外网的机器上装过PyTorch大概率经历过这种崩溃瞬间开发机上pip install torch俩小时就搞定到了内网服务器或者离线工作站却要么提示找不到满足要求的版本要么装完了一import就报缺cudnn、缺ninja、缺一堆莫名其妙的底层库最后折腾四五个小时连一个最简单的张量都没跑起来。这篇就是专门来解决这个问题的把PyTorch离线安装从版本选型、离线包准备、具体执行到验证排错整个流程拆开揉碎写一份可以直接照着操作的详细方案。适合谁来参考呢第一类是企业内网、政务网里的算法工程师和运维目标机器物理断网或者有严格的网络隔离第二类是高校实验室里分了共享工作站但外网权限受限的同学第三类是在边缘盒子、工控机、国产化服务器上部署PyTorch环境的开发。无论你是装CPU版跑推理还是要CUDA版做训练这套思路都通用。唯一的前提是你至少有一台能与外界联网、且和目标机器同为Linux/Windows的电脑用来准备离线包。1. 为什么说离线安装的核心问题不是装而是选很多人第一次做离线安装上来就动手结果翻车基本都翻在选错上。选错版本组合、选错Python标签、选错CUDA版本后面每一步都跟着出错。所以这一章先不谈命令把离线安装背后的逻辑讲透。1.1 三种最常见的离线安装场景物理断网的内网生产环境机房里有GPU服务器但整个网段与外网物理隔离或者只能通过堡垒机跳转数据不能出域。这种环境最常见也最严格需要一次性把环境准备到位。网络受限的共享实验室/工作站机器有网但只有HTTP代理或者白名单访问受限pip默认源根本连不通。这种情况下与其折腾代理配置不如直接走离线安装。边缘设备与工控机像Jetson小盒子、国产化工控机这类设备有的系统裁剪得很干净连装编译工具链都费劲更别说在线拉依赖了。这三种场景虽然断网方式不同但解决思路是一样的在联网端准备好一切搬到离线端去落地。1.2 离线安装和在线安装本质差在依赖解析在线安装时pip或conda会自动读取软件包的元数据然后去索引服务器上找依赖、找依赖的依赖层层解析最后把一整棵依赖树下载下来装好。离线安装没法做这一步你必须在联网机器上提前把这棵依赖树连根挖出来一次性打包带走。让我用个不恰当的比喻在线安装像是去饭店点菜你只需要说来一份鱼香肉丝后厨自己把各种材料备齐离线安装像是你家冰箱只有固定食材你必须自己想清楚做这道菜到底需要哪几种调料、哪个牌子的生抽漏掉一个这菜就炒不出来。所以离线安装的真实流程是先确定目标机器配置再反推出需要的版本组合然后在联网机器上手工完成依赖收集最后搬运过去安装。每一步的决策质量都直接决定你到了目标机器上要不要返工。1.3 从选型到落地的完整流程框架我的习惯是先画一条主线免得中间跑偏收集目标机器信息操作系统、CPU架构、GPU型号、NVIDIA驱动版本、现有Python版本。锁定版本组合PyTorch大版本、对应CUDA版本、对应Python版本列一个明确的requirements清单。在联网机器上用pip download或conda-pack准备离线包注意平台一致。通过任何可用方式U盘、内网网盘、SSH传输、审批后USB拷贝把包传到目标机器。在目标机器上执行离线安装优先用pip --no-index模式。跑验证脚本确认torch、CUDA、cuDNN全部就绪。记录环境快照方便后面在另一台离线机器上复现。这七步里第2步是最容易踩坑的地方也是下一章重点展开的内容。2. 动手前先定版本组合PyTorch、CUDA、Python的兼容三角这一步是离线安装的地基。版本选不对后面装得再辛苦都是白费。我自己见过太多人拿了个PyTorch 1.13的包往CUDA 12.1的机器上装装完一跑就报CUDA driver version insufficient还以为是机器驱动坏了。2.1 三者之间的依赖关系先理清一个基本事实PyTorch的GPU版不是自己实现CUDA的它是把CUDA运行时库libcudart、libcublas这类动态链接库一起打包在自己的wheel里然后调用NVIDIA驱动暴露的接口。所以这里其实有两条独立的依赖链PyTorch wheel内部的CUDA运行库这是安装包自带的不依赖目标机器装的CUDA ToolkitNVIDIA驱动提供的用户态驱动库这个决定你能跑哪个CUDA主版本比如驱动537系列支持CUDA 12.1驱动470系列最高只到CUDA 11.4。换句话说目标机器可以完全没装CUDA Toolkit只要NVIDIA驱动版本足够新PyTorch里的CUDA运行库就能直接跑起来。这也是离线安装经常让人困惑的地方——很多人以为要先装CUDA Toolkit其实对纯PyTorch环境来说不一定需要。Python版本的影响就简单了每个PyTorch wheel文件名的中间段会写明兼容的Python版本标签比如cp39代表CPython 3.9cp310代表3.10。目标机器Python是3.9就必须下载cp39标签的wheelcp310的包在3.9上装不了。2.2 怎么确认目标机器的GPU和驱动上限在动手之前先在目标机器上执行这几条命令摸清家底# 查看操作系统和CPU架构 uname -a cat /etc/os-release # 查看NVIDIA GPU型号和驱动 nvidia-smi # 如果没有nvidia-smi用lspci看GPU型号 lspci | grep -i nvidia # 查看Python版本如果有的话 python3 --version重点看nvidia-smi输出的右上角有一行CUDA Version: 12.1那表示当前驱动支持的最高CUDA版本是12.1。这意味着你可以放心使用带cu121后缀的PyTorch包。如果驱动只到CUDA 11.4非要装cu121版本的PyTorch那一运行就会出现驱动不支持的报错。2.3 我常用的几组稳定搭配这里给出几组我实际在生产环境用过的稳定组合可以直接照着选。Python版本PyTorch版本CUDA版本wheel后缀适用场景3.81.13.111.7cu117老项目、旧代码兼容3.92.0.111.8cu118稳定过渡期首选3.102.1.212.1cu121当前性价比最高的组合3.102.3.112.1cu121新项目推荐支持更新算子3.102.4.0以上12.4cu124最新特性但依赖驱动更苛刻注意PyTorch 1.x系列基本对应CUDA 10.2到11.7PyTorch 2.x系列从CUDA 11.8起步最新版已经到CUDA 12.4甚至12.8。如果你的目标机器是老旧GPU比如GTX 10系驱动可能只支持到CUDA 11.x那就老老实实选PyTorch 1.13.1cu117或者2.0.1cu118不要追求新版本。2.4 CPU版与国产GPU的选型差异如果目标机器根本没有NVIDIA GPU或者GPU不在PyTorch官方支持清单里比如部分国产GPU就需要转换思路纯CPU推理直接下载cpu后缀的wheel比如torch-2.3.1%2Bcpu-cp310-cp310-linux_x86_64。CPU版不需要CUDA依赖也少离线安装的报错概率大大降低。国产GPU像海光、寒武纪、昇腾这类设备PyTorch支持情况各不相同通常需要找硬件厂商提供的适配版PyTorch或专用SDK一般以完整的离线安装包形式分发装的时候优先按官方文档走。我在第六部分会详细说。3. 离线包来源的三种主流方案下载、打包、整目录搬运版本组合定了接下来就要在联网机器上准备离线包。这一步有三条路可以走各有优劣。3.1 方案一用pip download做全量wheel下载这是最通用、最常推荐的方式。在联网机器上对应目标机器的Python版本和操作系统执行mkdir torch_offline pip download torch2.3.1 torchvision0.18.1 torchaudio2.3.1 \ --index-url https://download.pytorch.org/whl/cu121 \ -d torch_offline这个命令不只是下载这三个包还会自动下载它们声明的所有运行时依赖比如numpy、pillow、sympy、typing_extensions、networkx等。全部落到torch_offline目录。这里有几个关键细节index-url必须指向PyTorch官方whl源直接敲pip install torch的话PyPI源里的wheel通常不带CUDA支持或者默认捆绑方式不一样所以指定cu121后缀很重要。wheel的文件名里包含平台信息比如linux_x86_64、win_amd64、linux_aarch64。联网机器和目标机器必须是同操作系统、同CPU架构、同Python大版本否则下载下来的包根本没法用。如果目标机器是纯CPU环境把index-url换成https://download.pytorch.org/whl/cpu。下载完成后务必清点目录里的全部文件。有个很常见的坑因为依赖解析差异有的机器上pip会自动跳过已满足的依赖导致离线包不完整。稳妥的办法是下载时加--no-deps先把主包拉下来再单独拉依赖或者下载完用下面的命令重新对照依赖树pip install --no-index --find-links./torch_offline torch2.3.1 21 | tail -50在联网机器上先这样演练一遍如果联网环境下能零缺依赖完成那么同样的包搬到离线机器上基本也就没问题。3.2 方案二conda-pack打包整个虚拟环境如果你的目标机器已经装了Anaconda/Miniconda而且你不想在离线环境里一个个装依赖conda-pack是最省心的。思路是在联网机器上生成一个完全独立且装好PyTorch的conda环境整包压缩搬到离线机器上解压直接用。联网端的步骤conda install -c conda-forge conda-pack conda create -n torch_env python3.10 -y conda activate torch_env pip install torch2.3.1 torchvision0.18.1 torchaudio2.3.1 \ --index-url https://download.pytorch.org/whl/cu121 conda pack -n torch_env -o torch_env.tar.gz目标端的步骤mkdir -p /home/user/anaconda3/envs/torch_env tar -xzf torch_env.tar.gz -C /home/user/anaconda3/envs/torch_env source /home/user/anaconda3/bin/activate torch_env python -c import torch; print(torch.__version__)这个方案的核心优势是conda-pack会把整个Python运行时、site-packages、bin目录里的可执行文件全部打进去目标机器甚至不需要提前安装独立Python只要有一个能激活环境的conda入口就行。缺点是包体积大一个CUDA版环境打下来常常超过4GB传文件时间会比较长。3.3 方案三整目录拷贝site-packages还有一种更野的路子在联网机器上创建虚拟环境装好PyTorch然后直接把venv目录或者conda环境的site-packages整个打包搬走。这种方案只推荐在无法联网、也无法用conda-pack的特殊情况下应急使用因为很容易漏掉一些非pip安装的依赖。具体做法python -m venv /tmp/venv_torch source /tmp/venv_torch/bin/activate pip install torch2.3.1 torchvision0.18.1 torchaudio2.3.1 \ --index-url https://download.pytorch.org/whl/cu121 cd /tmp tar -czf venv_torch.tar.gz venv_torch但我认真讲这个方案能跑通可是换一台机器、换个Python小版本就很容易出现找不到.so文件、ABI不兼容之类的问题。如果要用最好保证目标机器与联网机器的Python主版本完全一致同时还要把venv目录里的lib/python3.10/site-packages整个包含进去。能走前面两种方案就别用这个。3.4 传输过程中的路径与命名陷阱离线包准备好只是第一步传输过程也有讲究。拷贝到目标机器时注意两点目录路径不要带空格和中文更不要放在/mnt/c这类Windows挂载盘里在WSL2里尤其注意否则后续pip解析路径或者动态库加载都会出现奇怪的问题。wheel包名不要手动改名。torch-2.3.1cu121-cp310-cp310-linux_x86_64.whl这个名字里每个字段都是pip判定的依据改名等于破坏依赖解析。如果你嫌文件名长那是pip的正常现象别动它。4. 实操安装从纯pip离线到conda-pack迁移包到手了接下来就是正式安装了。这一章我给出最常用的两条路径完整步骤以及备选的离线编译方案。4.1 纯pip离线安装命令细节与顺序进入目标机器存放离线包的目录先安装下载好的全部依赖再装PyTorch本体。核心命令cd /path/to/torch_offline # 方式一一次性安装目录内所有wheel pip install --no-index --find-links./torch_offline torch torchvision torchaudio # 方式二显式指定wheel文件安装顺序为先依赖后主包 pip install --no-index --find-links./torch_offline numpy pip install --no-index --find-links./torch_offline torch-2.3.1cu121-cp310-cp310-linux_x86_64.whl \ torchvision-0.18.1cu121-cp310-cp310-linux_x86_64.whl \ torchaudio-2.3.1cu121-cp310-cp310-linux_x86_64.whl这里--no-index的作用是禁止pip去访问PyPI索引只认本地目录--find-links目录就是本地的唯一仓库。如果没有加--no-indexpip一旦发现本地包不满足还是会尝试联网最终要么卡死要么超时报错。装完以后用下面这条命令确认所有包都安装到位pip list | grep -Ei torch|torchvision|torchaudio|numpy|cudnn4.2 conda-pack环境迁移的细节补充conda-pack方案在目标端其实还有一个隐藏坑解压后环境里记录的是打包时的绝对路径而conda envs目录在目标机器上的绝对路径可能不一样。解决办法有两种把解压目录严格放到打包时相同的位置多数情况下conda环境在/anaconda3/envs/torch_env。或者修改环境里的bin/activate、conda-meta里的路径记录。但这个步骤繁琐不推荐新手操作。如果目标机器上恰好没有conda也可以不解压到envs目录而是直接把整个解压目录的bin/python可执行文件拿来用/path/to/unpacked_torch_env/bin/python -c import torch; print(torch.__version__)因为conda-pack打包的环境是自包含的bin/python会优先加载自身lib目录里的动态库不需要系统预装Python。4.3 离线源码编译最折腾但有时绕不开如果你要的PyTorch版本官方没有预编译wheel比如小众版本、特定国产芯片补丁就只能源码编译。严格意义上这不算离线安装但在内网环境里经常遇到。准备工作需要在联网机器上下载PyTorch源码、第三方依赖源码包以及编译需要的工具链。目标机器上至少需要gcc/g、make、cmake、python开发头文件python3-dev、ninja。很多离线服务器连gcc都是裁剪过的这一步真的是最痛苦的。编译PyTorch的简化流程tar -xzf pytorch-v2.3.1.tar.gz cd pytorch-v2.3.1 python setup.py bdist_wheel \ --cuda-home /path/to/cuda_local \ --build-type Release注意源码编译时CUDA相关库也需要从联网机器上提前完整拷贝进目标机器包括CUDA Toolkit的整个安装目录。这不推荐作为第一方案只建议在没有正式wheel可用的环境下使用。4.4 安装后的快速验证脚本无论用哪种方案安装完成后请先把下面这段Python脚本保存为check_torch.py然后执行import torch print(torch_version:, torch.__version__) print(python_version:, torch.version.python if hasattr(torch, version) else N/A) print(cuda_available:, torch.cuda.is_available()) if torch.cuda.is_available(): print(cuda_device:, torch.cuda.get_device_name(0)) print(cuda_version:, torch.version.cuda) print(cudnn_version:, torch.backends.cudnn.version()) a torch.randn(1000, 1000, devicecuda) b torch.randn(1000, 1000, devicecuda) c a b print(gpu_matmul_ok:, c.device) else: a torch.randn(1000, 1000) b torch.randn(1000, 1000) c a b print(cpu_matmul_ok:, c.shape)如果到最后一步能输出gpu_matmul_ok那环境就算真正通了。注意很多人只看到torch.cuda.is_available()是True就以为万事大吉其实还应该让GPU真实跑一次矩阵乘法因为某些离线包能加载但实际运行时缺libcudnn相关依赖一跑就崩。5. 装完了先别急着写代码验证输出与常见报错排查验证脚本跑完之后输出信息怎么解读、报错了怎么排查这章给你列清楚。我挑几个高频问题展开。5.1 验证输出怎么读torch.__version__的输出如果末尾带cu121比如2.3.1cu121说明这个包确实是CUDA编译版如果是cu118对应CUDA 11.8如果是cpu就是纯CPU版。torch.cuda.is_available()输出False时先别怀疑离线包有问题按这个顺序排查目标机器有没有NVIDIA GPUlspci | grep -i nvidia没有就是硬件层面不支持。驱动安装情况nvidia-smi能不能跑报command not found说明驱动根本没装。用户权限除非在Docker、LXC这类容器环境里否则/dev/nvidia0这类设备是否可见root账户下验证更稳妥。wheel的CUDA版本是否和驱动匹配上一章说的驱动上限问题这里最常暴露。5.2 五大高频报错与解决方法报错根因处理ModuleNotFoundError: No module named torch环境不对或没装上which python检查解释器路径确认site-packages里有torch目录ImportError: libcudart.so.12: cannot open shared object fileCUDA运行库缺失或不在系统搜索路径用LD_LIBRARY_PATH指向torch包内部的lib目录或安装CUDA的运行库ImportError: libGL.so.1: cannot open shared object file系统缺libGL图形库离线安装libgl1、libglib2.0等基础库或直接从联网机器拷对应deb包OSError: /usr/lib/x86_64-linux-gnu/libcuda.so.1: symbol lookup error系统CUDA库与PyTorch包冲突删除或重命名单独安装的cuda库让PyTorch自带版本生效undefined symbol: _ZN5c10...不同版本的libtorch_cpu/libc10混在一起把site-packages里所有torch相关目录清干净重新离线安装这里面最让人头疼的组合往往是第二和第四类目标机器上原本装过别的CUDA软件把系统级libcudart.so和PyTorch自带libcudart.so搞混了。对我来说遇到这种环境冲突最直接的办法是设置LD_LIBRARY_PATH强制优先加载PyTorch包内库而不是动系统目录。export LD_LIBRARY_PATH/path/to/python/lib/python3.10/site-packages/torch/lib:$LD_LIBRARY_PATH但这个方法也有副作用它会影响同一终端里其他程序。建议只在启动训练脚本时临时加不要写进全局环境变量。5.3 CUDA运行库的三种搬运姿势如果确实需要为离线环境准备CUDA运行库三种姿势分别应对不同需求直接不装CUDA Toolkit依赖PyTorch自带库适合纯PyTorch训练和推理最省事。强制要求NVIDIA驱动匹配即可。拷贝CUDA Toolkit的完整安装目录适合还要编译CUDA扩展或跑其他CUDA程序的环境。离线拷贝时注意保留bin、lib64、include三个核心子目录的结构。用conda安装cudatoolkit离线包适合conda管理场景直接通过conda的本地缓存和离线channel安装cudatoolkit和cudnn版本由conda解析兼容性略好。6. 特殊环境实战银河麒麟V10、海光GPU与WSL2的离线安装热搜词里有一堆关于麒麟系统V10 海光GPU和WSL2的提问这两个场景在实践中概率不低单独拿出来说。6.1 银河麒麟V10与海光GPU的离线安装要点麒麟V10通常基于Debian或Ubuntu系开发常见CPU架构是x86_64和aarch64。在它上面装PyTorch总体流程和标准Ubuntu类似但有三个明显差异系统的Python资源不可控麒麟自带的Python3可能是3.7或3.8而且和系统底层包深度绑定直接pip容易污染系统。强烈建议用Miniconda隔离。缺少基础依赖包麒麟V10的最小化安装可能没有libgl、libgomp之类pip装PyTorch时会遇到缺系统库的报错。需要提前准备对应麒麟版本的deb包或者用conda环境自带的库规避。HaiGuang GPU的驱动与SDK链海光GPU的PyTorch支持通常要装海光官方提供的适配SDK它一般自带特定版本的PyTorch离线安装包。实际项目里我的建议是先看厂商SDK文档确认官方推荐的PyTorch版本和Python版本再反推CUDA/ROCm层。不要试图从官方PyTorch源下载通用CUDA版来跑海光GPU那大概率识别不了设备。具体的离线安装步骤和通用流程一致第一步确认系统版本和架构uname -m看是不是x86_64第二步装Miniconda离线包第三步用conda创建Python环境第四步安装厂商SDK里的whl包或者官方PyTorch的CPU版第五步验证GPU加速是否真正生效。如果验证时torch.cuda.is_available()为False多半是驱动层和用户态库版本没对上需要回到厂商SDK的版本矩阵重新核对。6.2 WSL2环境下离线安装的注意事项WSL2现在几乎是Windows下做PyTorch开发的标准姿势。如果你是在WSL2里离线安装和纯Linux机器相比有几个独特的地方第一WSL2的GPU驱动是Windows侧提供的Linux内核里不装NVIDIA Linux驱动。所以你的nvidia-smi命令实际上是从Windows驱动转出来的输出里的驱动版本也是Windows发行版的信息。这不影响你在Linux环境里装PyTorch的CUDA版但如果你习惯性先去下载Linux驱动安装包就会卡在装驱动这个环节出不来——WSL2里根本不需要也装不了Linux原生驱动。第二离线包文件不要放在/mnt/c或者/mnt/dWindows文件系统挂载点下安装。WSL2对/mnt/c的IO性能差而且某些动态库在跨文件系统执行时权限和依赖加载会出问题。正确姿势是放在Linux侧的家目录比如/home/user/torch_offline。第三WSL2的网络默认是NAT模式即使Windows能上网WSL2里面访问外网也依赖Windows宿主代理转发。如果你们公司有严格网络限制WSL2里断网的感觉和物理机一样你要做的就是把离线包从Windows侧通过cp命令复制进Linux侧再按通用流程安装。6.3 AMD GPU在WSL2或Linux下的选择如果你的显卡是AMD比如Radeon 7900XTX事情就变成了另一条分支PyTorch官方虽然有ROCm版本但WSL2下的ROCm支持一直没有NVIDIA驱动那样开箱即用需要额外安装ROCm for WSL的预编译包再选对PyTorch对应ROCm版本的wheel。离线安装思路完全相同只是下载时要认准rocm6.x后缀的wheel。这个问题能展开写好几篇文章这里点到为止提醒你提前确认显卡和ROCm版本的匹配矩阵再动手。7. 离线安装的版本锁定、模型导出与长期维护环境最终跑起来了但事情并没有结束。离线环境往往不像开发机那样随时能加包后续每动一个版本、每导出一次模型藏着的坑都在等你。7.1 版本锁定的最佳实践我强烈建议你在安装成功后立刻做两件事第一生成requirements快照pip freeze requirements_offline.txt conda env export environment_offline.yml这两份文件是离线环境的时间和事实记录。下次需要在新机器复现时直接照着这个清单准备离线包能少走很多弯路。第二把离线包目录本身当作资产保存不要装完就删。在网盘或NAS里按pytorch-2.3.1-cu121-py310这样的命名归档再写一个README.txt记录来源和校验hash。你会发现隔半年要重装时这堆旧包比什么文档都靠谱。7.2 PyTorch转ONNX时的版本一致性搜索热词里有pytorch转onnx我在离线环境里也踩过对应的坑。PyTorch导出ONNX模型时torch.onnx.export依赖一个与Torch捆绑的ONNX解析器和算子映射表不同PyTorch版本支持的ONNX opset版本不完全相同导出的算子图也不同。在离线环境里你需要提前把对应版本的onnx、onnxruntime装好并确认与PyTorch大版本兼容PyTorch 1.13和2.0导出时的默认opset版本不同如果后续部署环境用了更高opset可能出现不支持的算子报错导出时加上dynamoTruePyTorch 2.x或者走过去常见的torch.jit.trace路径对算子的支持范围也有差异。离线环境加包困难所以尽量在最初安装时就把onnx和onnxruntime一起纳入离线包清单免得好不容易装完训练环境临导出模型时发现缺少onnx、又要重新走一遍传输流程。7.3 一点实操体会我个人的经验是离线安装PyTorch真正困难的从来不是某一条pip命令而是一个预则立的工程问题——版本矩阵没理清、依赖树没收全后面怎么补救都别扭。还有一个容易被忽视的小诀窍如果你手头要维护多台同样配置的离线机器别一台台折腾把整个pip离线目录和requirements文件放到一台基准机器上验证无误之后直接打包分发。一台机器从头到尾跑通剩下几台机器用同样的包一路pip install不出十分钟全部就绪。踩过一次来回搬运的坑之后你会意识到这步规划有多值钱。到最后还是想说那句老话断网不可怕可怕的是断网之前没有想清楚要装什么。希望这篇能在你下次面对离线环境时帮你少一点抓瞎、多一点底气。