1. 从CPU到GPU：一次彻底的PyTorch环境迁移
最近在帮一个朋友处理他的深度学习项目，他之前一直用CPU版本的PyTorch跑模型，训练一个简单的图像分类任务都要等上大半天。项目临近交付，时间紧迫，他终于下定决心要把环境切换到GPU上。他的机器是一台配备了RTX 4090的工作站，驱动和CUDA都已经装好了，但公司内网环境限制，无法直接联网下载。这其实是一个挺典型的场景：手头有性能强大的硬件，却因为环境限制卡在软件安装这一步，空有“屠龙刀”却使不上劲。
从CPU版本的PyTorch和torchvision切换到GPU版本，远不止是运行一个pip install命令那么简单。这背后涉及到CUDA工具包版本、PyTorch版本、torchvision版本，乃至Python版本和操作系统之间的精确匹配。一个环节出错，就可能遇到经典的CUDA error: no kernel image is available for execution或者torch.cuda.is_available()返回False的窘境。离线安装更是放大了这个过程的复杂度，你需要提前把所有依赖的“零件”都准备好，并且确保它们严丝合缝。
这篇文章，我就以这次实际的“救援”经历为蓝本，拆解在离线环境下，将CPU版PyTorch/torchvision环境完整迁移到GPU版本的全过程。我会重点解释每个步骤背后的逻辑，而不仅仅是给出命令。无论你用的是RTX 3050、4090，还是其他NVIDIA显卡，无论你是Ubuntu、Windows，还是WSL2环境，这套离线迁移的思路都是相通的。我们会从理清版本依赖关系开始，到准备离线安装包，再到处理棘手的依赖冲突，最后完成验证。如果你也正对着内网里那台“有力使不出”的GPU机器发愁，希望这篇手把手的指南能帮你把路趟平。
2. 版本对齐：构建你的专属“兼容性矩阵”
离线安装最大的挑战在于“开弓没有回头箭”。你不能像在线环境那样，先pip install torch，发现版本不对再pip install torch==xxx来回试错。所有组件必须在安装前就确保兼容。因此，第一步不是下载，而是制定一个精确的安装蓝图。
2.1 核心三角：PyTorch、CUDA与驱动
首先，要理解GPU版PyTorch运行的核心依赖链：NVIDIA显卡驱动 -> CUDA Toolkit -> PyTorch (with CUDA) -> torchvision。这是一个自底向上的依赖关系。
- NVIDIA驱动：这是最底层的软件，让操作系统能识别和控制你的GPU。你可以通过
nvidia-smi命令查看驱动版本和显卡信息。这个命令输出的右上角会显示CUDA Version: 12.4之类的信息，这指的是此驱动最高支持的CUDA运行时版本，不代表你已经安装了该版本的CUDA Toolkit。 - CUDA Toolkit：这是NVIDIA提供的并行计算平台和编程模型。PyTorch的GPU运算内核（kernel）是用CUDA C++编写的。你需要安装一个特定版本的CUDA Toolkit（包含编译器nvcc、库文件等）。PyTorch预编译的二进制包（wheel文件）是针对特定CUDA版本编译的，例如
cu121表示针对CUDA 12.1编译。 - PyTorch：你需要下载与你的CUDA Toolkit版本匹配的PyTorch wheel文件。例如，如果你安装了CUDA 12.1，就应该寻找
torch-2.x.x+cu121的包。 - torchvision：这个计算机视觉库与PyTorch版本紧密绑定。它同样需要匹配PyTorch的主版本和CUDA版本。
2.2 如何确定你的“目标版本”
假设我们朋友的机器运行nvidia-smi显示驱动版本为545.xx，支持CUDA 12.3。一个稳妥的选择是安装CUDA 12.1 Toolkit，因为PyTorch对CUDA 12.1的支持非常成熟和稳定。接下来，我们访问PyTorch官网的历史版本页面（https://pytorch.org/get-started/previous-versions/），而不是首页，因为首页只提供最新版本的安装命令。
我们的目标是找到形如这样的离线安装命令所对应的文件：pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu121
从这条命令我们可以解析出：
- PyTorch版本：2.1.0
- torchvision版本：0.16.0
- CUDA版本：cu121 (即12.1)
- Python版本：需要根据wheel文件名进一步判断（如
cp310表示Python 3.10）
2.3 制作你的版本检查清单
在开始下载前，请务必填写下面这个清单：
| 组件 | 目标版本 | 确认命令/方法 | 备注 |
|---|---|---|---|
| 操作系统 | Ubuntu 22.04 | cat /etc/os-release | Windows需注意是Win10/11 |
| Python | 3.10 | python --version | 强烈建议使用conda或venv创建独立环境 |
| NVIDIA驱动 | 545.xx | nvidia-smi | 确保支持目标CUDA版本 |
| CUDA Toolkit | 12.1 | 计划安装 | 选择与PyTorch预编译包匹配的版本 |
| PyTorch | 2.1.0+cu121 | 待下载 | wheel文件名包含cu121 |
| torchvision | 0.16.0+cu121 | 待下载 | 必须与PyTorch版本严格对应 |
注意：
torchaudio如果你不需要可以忽略。但torch和torchvision的版本对应关系必须严格遵守。一个常见的错误是混用版本，导致导入时报错RuntimeError: operator torchvision::nms does not exist，这通常就是因为torchvision中的C++扩展与PyTorch核心库不兼容。
3. 离线资源猎取：下载所有必需的“拼图”
有了明确的版本清单，我们就可以去有网络的环境下载所有必需的安装包了。这里的关键是：不仅要下载主包，还要下载其所有依赖的离线包。
3.1 主包下载：PyTorch与torchvision
最可靠的方式是直接从PyTorch官方的CDN下载。根据我们的清单（Python 3.10, CUDA 12.1, Linux），我们需要寻找以下文件：
torch-2.1.0+cu121-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whltorchvision-0.16.0+cu121-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
你可以通过拼接官方索引URL来直接下载：
https://download.pytorch.org/whl/cu121/torch-2.1.0%2Bcu121-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl https://download.pytorch.org/whl/cu121/torchvision-0.16.0%2Bcu121-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl（注意URL中的%2B就是加号+的编码）
对于Windows系统，文件名会类似torch-2.1.0+cu121-cp310-cp310-win_amd64.whl。
3.2 依赖包下载：解决“多米诺骨牌”问题
PyTorch和torchvision本身依赖其他Python包，如numpy,pillow,requests等。在离线环境下，如果这些依赖不存在，安装主包也会失败。我们需要使用pip download命令来打包所有依赖。
在有网的环境，创建一个干净的目录，并准备一个与目标环境一致的Python环境（版本相同）。然后执行：
pip download torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cu121 -d ./offline_packages这个命令会解析torch和torchvision的依赖树，并将所有需要的.whl或.tar.gz文件下载到./offline_packages目录。你会看到除了torch和torchvision的主包，还多了很多如numpy,pillow等包。
3.3 CUDA Toolkit的离线安装包
对于CUDA Toolkit，你需要从NVIDIA官网下载离线安装包（runfile格式）。以CUDA 12.1 Update 1为例，选择Linux -> x86_64 -> Ubuntu -> 22.04 -> runfile (local)。你会得到一个名为cuda_12.1.1_530.30.02_linux.run的大文件（约3GB）。这个文件包含了安装所需的所有内容。
实操心得：下载CUDA runfile时，页面通常会提供一个基础安装命令和补丁。对于离线安装，我们只需要这个最大的
runfile (local)文件。务必确认操作系统版本和架构（x86_64）选择正确。
至此，你应该准备好了一个包含以下内容的离线安装包文件夹：
cuda_12.1.1_530.30.02_linux.run(CUDA Toolkit)torch-...cu121....whltorchvision-...cu121....whlnumpy-....whlpillow-....whl- ... (其他一堆依赖包)
将这个文件夹完整地拷贝到你的离线目标机器上。
4. 按序施工：离线环境下的安装与配置
现在，我们回到离线机器上。安装顺序至关重要：先装CUDA，再装Python依赖，最后验证。
4.1 第一步：安装CUDA Toolkit（如果未安装）
如果你的机器已经安装了其他版本的CUDA，或者不确定是否需要安装，可以先检查：nvcc --version。如果命令不存在或版本不对，则进行安装。
- 给runfile添加执行权限：
chmod +x cuda_12.1.1_530.30.02_linux.run - 运行安装程序，并关键地，取消驱动安装：
在安装界面中，你会看到有安装驱动的选项。因为我们已经有了更新的驱动（545.xx），而此CUDA包自带的驱动版本（530.30.02）较旧，所以务必用空格键取消勾选sudo ./cuda_12.1.1_530.30.02_linux.runDriver的安装，只安装CUDA Toolkit。 - 配置环境变量。安装程序通常会提示你将以下内容添加到
~/.bashrc（或~/.zshrc）中：
添加后，执行export PATH=/usr/local/cuda-12.1/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}source ~/.bashrc使其生效。然后验证nvcc --version，应显示Cuda compilation tools, release 12.1, V12.1.105。
踩坑记录：这里最容易出错的就是安装了旧版驱动，导致与现有显卡驱动冲突，可能引起图形界面崩溃。一定要仔细看安装界面，只装Toolkit。
4.2 第二步：在独立的Python环境中离线安装PyTorch家族
强烈建议使用Conda或venv创建一个独立的Python环境，避免污染系统环境。
# 使用conda conda create -n pytorch_gpu python=3.10 -y conda activate pytorch_gpu # 或使用venv python3.10 -m venv pytorch_gpu_env source pytorch_gpu_env/bin/activate激活环境后，进入存放所有离线包的目录，使用pip install直接安装本地文件：
pip install torch-2.1.0+cu121-cp310-cp310-*.whl torchvision-0.16.0+cu121-cp310-cp310-*.whl --find-links . --no-index--find-links .：告诉pip在当前目录查找包。--no-index：禁止pip连接网络索引。
这条命令会优先安装你指定的两个whl文件，并自动从当前目录解析并安装它们的所有依赖。如果遇到依赖缺失，pip会报错，你需要检查pip download阶段是否漏掉了某个包，将其补进目录即可。
5. 验证与排错：确保GPU真正可用
安装完成不代表成功。我们必须进行一系列验证，确保PyTorch能正确识别并使用GPU。
5.1 基础验证脚本
创建一个简单的Python脚本verify_gpu.py：
import torch print(f"PyTorch版本: {torch.__version__}") print(f"CUDA是否可用: {torch.cuda.is_available()}") if torch.cuda.is_available(): print(f"GPU设备数量: {torch.cuda.device_count()}") print(f"当前GPU设备: {torch.cuda.current_device()}") print(f"设备名称: {torch.cuda.get_device_name(0)}") # 进行一次简单的张量运算测试 x = torch.randn(3, 3).cuda() y = torch.randn(3, 3).cuda() z = x + y print(f"GPU计算测试成功，结果形状: {z.shape}") else: print("警告：CUDA不可用！")运行它：python verify_gpu.py。理想情况下，你会看到CUDA可用，设备名称为你的显卡（如NVIDIA GeForce RTX 4090），并且测试计算成功。
5.2 常见故障排查
如果torch.cuda.is_available()返回False，请按以下链路排查：
- 驱动与CUDA版本不匹配：再次运行
nvidia-smi和nvcc --version，确认驱动支持的CUDA版本（例如12.4）大于等于你安装的CUDA Toolkit版本（例如12.1）。只要大于等于即可，这是向后兼容的。 - PyTorch与CUDA版本不匹配：这是最可能的原因。在Python中运行
print(torch.version.cuda)。这个输出必须与你安装的CUDA Toolkit版本（nvcc --version）的主次版本号一致。例如，torch.version.cuda输出12.1，nvcc输出release 12.1，这才匹配。如果一个是11.8，一个是12.1，那肯定失败。你需要重新下载对应版本的PyTorch wheel包。 - 环境变量问题：确保
LD_LIBRARY_PATH包含了CUDA的库路径（/usr/local/cuda-12.1/lib64）。有时在虚拟环境中需要显式设置。 - 显卡架构不支持：极少数情况下，会遇到
CUDA error: no kernel image is available for execution。这通常发生在PyTorch预编译包的CUDA算力（如sm86）与你的显卡计算能力（如RTX 4090是sm89）不匹配。PyTorch官方包通常支持主流算力。如果遇到此问题，可能需要从源码编译PyTorch，但这在离线环境下极其复杂。更简单的办法是尝试PyTorch版本页面上其他相近的CUDA版本预编译包。
5.3 卸载原有的CPU版本
在验证GPU版本工作正常后，如果你是在同一个Python环境中操作，CPU版本的torch应该已经被覆盖。但为了绝对干净，你可以先卸载旧包，再重新安装本地GPU包：
pip uninstall torch torchvision torchaudio -y # 然后再次执行本地安装命令 pip install torch-2.1.0+cu121-*.whl torchvision-0.16.0+cu121-*.whl --find-links . --no-index6. 进阶考量与长期维护
一次成功的离线安装只是开始。如何维护这个离线环境，并在未来可能升级？
6.1 构建本地wheel仓库
对于需要频繁在内网部署相似环境的团队，可以搭建一个本地的PyTorch wheel仓库。你可以使用pip download下载一整套特定版本组合（如PyTorch 2.1.0 + CUDA 12.1 for Python 3.8/3.9/3.10/3.11）的所有包，然后使用pip install的--index-url指向一个本地的HTTP服务器（如用python -m http.server简单搭建）或专业的仓库管理工具。这样，内网机器的安装命令就和在线几乎一样了，只是索引地址换成了内网地址。
6.2 使用Docker镜像进行分发
这是更彻底和优雅的解决方案。在有网的环境，拉取或构建一个包含正确版本PyTorch GPU环境的Docker镜像（例如pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime）。然后将这个镜像保存为文件（docker save -o pytorch_gpu.tar image:tag），拷贝到离线机器上加载（docker load -i pytorch_gpu.tar）。这种方式完美封装了所有依赖，包括系统库，环境一致性最强。
6.3 版本升级路径
当需要升级时（例如从PyTorch 2.1升级到2.2），重复上述过程：在有网环境根据新版本确定兼容矩阵，下载新的离线包（包括新版本可能引入的新依赖），在离线环境创建新虚拟环境进行安装测试，稳定后再迁移项目。切忌直接在老环境上升级，很容易造成依赖地狱。
整个离线迁移的过程，像是一次精密的仪器组装。核心在于前期充分的“图纸规划”（版本匹配），中期完整的“零件备货”（依赖下载），以及后期细致的“安装调试”（按序安装与验证）。最深的体会是，在离线环境下，耐心和细致远比技术本身更重要。每次动手前，多花十分钟核对版本号，能省下后面数小时的排错时间。当你终于看到torch.cuda.is_available()返回True，并且模型训练速度提升数十倍时，这一切的麻烦都是值得的。
