从装好 GPU 驱动到跑通torch.cuda那一步中间踩的坑比想象中多得多。很多人卡在一个很奇怪的位置驱动装了CUDA 装了PyTorch 也能import但一跑模型风扇就是不转控制台默默提示Using CPU。查了半天才发现要么是 CUDA 版本和 PyTorch 的预编译版本对不上要么是 cuDNN 放错了目录根本没生效。这篇就从头到尾把 CUDA cuDNN PyTorch 的安装链路理一遍Windows 和 Linux 都会讲到重点放在版本匹配逻辑和装完之后的验证方法上。1. 动手前先搞清版本匹配否则后面全白搭1.1 显卡驱动和 CUDA Toolkit 到底是什么关系先说一个最常见的误区很多人以为装了显卡驱动就等于装了 CUDA然后直接跑nvcc -V发现命令不存在就慌了。实际上这两件事是分开的。NVIDIA 显卡驱动是让系统能识别并调用 GPU 的底层程序而 CUDA Toolkit 是给开发者用的编译器和库集合。你可以把驱动理解成硬件能用CUDA Toolkit 理解成软件能跑。驱动里面其实自带了一个运行时版的 CUDA 库这就是为什么你在命令行敲nvidia-smi右上角会显示一个CUDA Version: 12.8。这个版本号指的是当前驱动支持的最高 CUDA 版本不代表你已经安装了完整工具链。判断一块显卡支持到什么程度直接看nvidia-smi的输出--------------------------------------------------------------------------------------- | NVIDIA-SMI 545.84 Driver Version: 545.84 CUDA Version: 12.3 | ---------------------------------------------------------------------------------------上面这行信息意味着你的驱动最多能跑 CUDA 12.3 及以下版本的程序但你现在这个机器上不一定装了 CUDA Toolkit 12.3。这里引出一个重要操作原则先装驱动后装 CUDA Toolkit再装 cuDNN最后装 PyTorch顺序不要反。驱动是整个链路的底层支撑其他所有组件都是基于它运行的。1.2 算力和 CUDA 版本的对应关系4060 Ti 用户尤其注意GPU 有一个叫算力Compute Capability的东西用CC表示格式是8.6、8.9、9.0这种。PyTorch 和 cuDNN 在编译和运行时会针对不同算力做优化。如果驱动的 CUDA 版本太老不认新显卡的算力那 PyTorch 编译出来的一些算子就加载不上最终表现为各种诡异的报错比如no kernel image is available for execution on the device。以下是常见 N 卡架构和对应的算力、最低 CUDA 版本支持GPU 架构代表显卡算力最低驱动版本约建议 CUDA ToolkitAmpereRTX 30 系8.647011.x / 12.xAda LovelaceRTX 40 系8.952511.8 / 12.xHopperH1009.052512.xTuringRTX 20 系 / GTX 16 系7.541810.x / 11.xBlackwellRTX 50 系12.0 / 12.155012.8 / 13.xRTX 4060 Ti 是 Ada Lovelace 架构算力 8.9.这卡有个微妙的地方它最低能跑 CUDA 11.8但部分 PyTorch 的cu118预编译包里默认的算子编译目标只到安培架构的 8.6虽然后续补了sm_89的支持但你会发现有些手动编译的扩展比如某些自定义算子、SageAttention 这类优化库在编译时如果检测不到算力信息就会直接报could not determine cuda architec这类错误。我的建议是2024 年以后的新机器直接上 CUDA 12.x不要去碰 11.x。12.x 对 Ada 架构的适配更完整而且 PyTorch 官方对cu121、cu124、cu126、cu128这些版本的预编译包支持是最积极的。1.3 用 PyTorch 官网的版本表反推出你要装什么PyTorch 官方提供了一个非常关键的页面https://pytorch.org/get-started/locally/。你在这个页面选择你的操作系统、包管理器、CUDA 版本它会自动生成对应的安装命令。但要注意一个反直觉的点官网生成的命令不一定是你能用的。比如它默认会给你一个pip install torch torchvision torchaudio不带任何 CUDA 的--index-url参数。如果你直接复制这条命令很有可能会从 PyPI 装到 CPU 版或者装到一个和你驱动不匹配的旧版。正确做法是先在页面 CUDA 版本选项里明确选择一个通常是12.1、12.4或12.8然后复制带--index-url的那条命令。这件事后面第四章我会详细拆。版本匹配的整个逻辑链其实就一句话驱动版本 ≥ CUDA Toolkit 版本 ≥ PyTorch 预编译版本 ≥ cuDNN 依赖的 CUDA 版本。只要这条链路不乱后面基本稳。2. 动手装 CUDAWindows 和 Linux 各有各的坑2.1 Windows 下安装 CUDA Toolkit 的正确姿势Windows 下安装 CUDA 核心就是去 NVIDIA 官网的CUDA Toolkit下载页面选版本、选操作系统、选安装包类型。这里有几个关键选择要注意下载方式的选择exe (local)本地安装包离线安装体积大2-3GB但是安装过程最稳定。exe (network)网络版安装包体积小但安装时会实时从服务器拉取文件网络不稳定容易失败。我的建议是用 local 版本。虽然下载时间长一点但省去安装过程中断重来的痛苦。安装过程的关键选项双击安装后在选择安装类型界面选自定义而不是精简。因为精简安装会默认把 NVIDIA 显卡驱动也重新装一遍这是很多环境被搞坏的原因——你用精简安装覆盖了原驱动结果装完nvidia-smi显示版本变了部分老项目开始报驱动版本太低。在自定义安装的组件列表中你会看到CUDA里面包含 Runtime、Development、Visual Studio Integration 等子项Driver components这个一定要取消勾选除非你的驱动版本比这个还老其他附加组件这里有一个常见报错在 Windows 上安装时弹出CUDA Visual Studio Integration ... no supported version of Visual Studio was found很多人在这一步感觉天塌了以为安装失败了。实际上这个报错只影响你在 Visual Studio 里用 CUDA 的图形化调试插件不影响命令行编译 CUDA 程序也不影响 PyTorch 调用 GPU。如果你不写 C 的 CUDA 扩展完全可以忽略这个警告继续安装。装完之后nvcc -V就能用了。但注意如果nvcc -V报不是内部或外部命令说明环境变量没配好。CUDA 安装器默认会自动添加环境变量但有时因为路径里包含空格或者安装目录被修改会导致环境变量不生效。检查系统环境变量里的Path确认是否包含以下几条C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\binC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\libnvvpC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\extras\CUPTI\lib64C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include如果你安装的时候自定义了路径就按实际路径改。改完环境变量之后新开的命令行窗口才会生效。2.2 Linux 下 .run 文件安装及 gzip 报错处理Linux 环境下装 CUDA我推荐用.run文件而不是 deb 包。.run文件可以指定安装目录方便多版本共存而且对系统自带的驱动影响小。下载页面里选runfile (local)即可。拿到.run文件后先不要急着执行我这里有个血泪教训。很多人直接跑sudo sh cuda_12.8.0_560.28.03_linux.run然后报一个极其诡异的错误gzip: stdin: invalid compressed>sudo sh cuda_12.8.0_560.28.03_linux.run --tmpdir/home/username/tmp执行之后会进入一个字符交互界面。第一个问题问是否安装 NVIDIA Accelerated Graphics Driver for Linux一定要选 No。因为服务器或者个人机器上的显卡驱动一般都提前装好了重复安装驱动轻则覆盖驱动导致nvidia-smi失效重则因为和内核版本不匹配导致黑屏。剩下的选项CUDA Toolkit 选 YesCUDA Samples 可以根据需要选符号链接symlink建议选 Yes这样/usr/local/cuda会指向你刚装的这个版本后续很多编译工具默认找这个路径。安装完成后把 CUDA 相关的路径加入环境变量编辑~/.bashrcexport PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH保存后执行source ~/.bashrc然后nvcc -V检查是否生效。2.3 nvcc -V 和 nvidia-smi 版本不一致是正常现象装完 CUDA 后你在终端跑nvcc -V可能显示 12.8跑nvidia-smi显示CUDA Version: 12.8但这个正常的版本一致有时不会发生——比如nvcc -V显示 12.4nvidia-smi显示 12.8这不是故障。nvidia-smi里的CUDA Version指的是驱动能支持的最高版本nvcc -V里的release指的是编译器实际使用的版本。打个比方驱动是一个平台它可以承载比你当前装的更低版本的 CUDA但你实际编译程序用的版本由nvcc决定。所以只要满足驱动的 CUDA 支持版本 ≥ nvcc 的版本那这套环境就是可用的。如果你发现nvidia-smi显示 12.8nvcc -V显示 12.4完全不用慌先用 12.4 干活就行。只有当nvcc -V的版本比驱动支持的还高时才需要去升级驱动或降低 CUDA Toolkit 版本。3. cuDNN 安装本质就是复制文件但复制错了地方等于白装3.1 cuDNN 到底是什么东西cuDNNCUDA Deep Neural Network library是 NVIDIA 专门为深度学习设计的一个高性能加速库里面用深度优化的矩阵乘法和卷积实现把 GPU 的计算潜力榨干。PyTorch 在 GPU 上跑卷积神经网络时底层大量调用的就是 cuDNN 的算子。严格来说PyTorch 的预编译包里已经内置了一部分 cuDNN 的运行时库。所以有些人没装 cuDNNPyTorch 照样能跑起来。但这里有个性能隐患内置的版本可能比较旧某些新型卷积算子的性能不是最优的。另外如果你想编译 TensorFlow 或其他需要显式链接 cuDNN 的框架就必须自己装 cuDNN。cuDNN 的版本编号中间也有门道。之前 cuDNN 8.x 对应 CUDA 11.xcuDNN 9.x 对应 CUDA 12.x。下载时一定要对应上 CUDA 版本。比如你已经装了 CUDA 12.8那就应该下载 cuDNN 9.x for CUDA 12.x。cuDNN 下载页面会让你先注册登录后选择匹配的版本。3.2 Windows 下 cuDNN 安装三个目录的规则Windows 下解压 cuDNN 的压缩包你会看到里面有三个文件夹bin、include、lib。所谓的安装就是把这三个文件夹里的文件分别复制到 CUDA 安装目录对应的同名文件夹里。具体来说把解压后的bin\cudnn*.dll复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin把解压后的include\cudnn*.h复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include把解压后的lib\x64\cudnn*.lib复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\lib\x64这个复制过程的原理其实很简单CUDA 的编译器在编译程序时会去include目录找头文件运行时去bin目录找 DLL 动态链接库链接时去lib\x64目录找.lib静态导入库。三个目录各管一摊少一个都会出问题。最容易犯的错是只复制了include和lib忘了把bin下的 DLL 复制过去。结果编译时一切正常一运行就报DLL load failed或者error while loading shared libraries这就是典型的编译能找到头文件但运行时找不到动态库。我常用的验证方法是打开命令行进入到包含cudnn_ops_train64_9.dll的目录也就是 CUDA 的 bin 目录然后执行where cudnn64_9.dll正常情况下能返回完整路径。如果不能返回说明bin目录里的文件没复制到位或者环境变量没配好这就相当于 cuDNN 没装上。3.3 Linux 下 cuDNN 安装与验证Linux 下 cuDNN 离线包一般是.tar.gz格式。下载解压后同样是把对应文件复制到 CUDA 目录里tar -xzvf cudnn-linux-x86_64-9.5.0.50_cuda12-archive.tar.xz cd cudnn-linux-x86_64-9.5.0.50_cuda12-archive sudo cp include/cudnn*.h /usr/local/cuda/include/ sudo cp lib/libcudnn* /usr/local/cuda/lib64/ sudo chmod ar /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*最后这个chmod ar很重要否则非 root 用户编译时没有权限读取这些文件会报Permission denied。装完以后查询 cuDNN 版本我一般用两种方式看文件内容cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2如果文件不存在说明头文件复制路径不对。编译官方测试样例cp -r /usr/local/cuda/samples /home/username/cuda_samples cd /home/username/cuda_samples/1_Utilities/deviceQuery make ./deviceQuery这个deviceQuery会输出显卡详细信息如果最后一行显示Result PASS说明 CUDA 本身没问题。想测 cuDNN 的话看simpleConvolution那个样例它能跑通就意味着 cuDNN 的库链路是通的。4. PyTorch 安装一个参数之差CPU 版和 GPU 版天壤之别4.1 为什么 pip 默认装的是 CPU 版PyTorch 在 PyPI 上长期存在的默认版本是 CPU 版。也就是说如果你直接执行pip install torch装下来的是只能跑 CPU 的版本完全用不上显卡。这事让很多人栽过跟头看到官网命令是pip install torch torchvision torchaudio复制下来就装装完进 Python 跑torch.cuda.is_available()一直返回False其实原因是这个默认命令根本没有指定 CUDA 编译版本。正确的做法是从 PyTorch 官网的左下角选好操作系统、包管理器、CUDA 版本然后复制生成的那条带--index-url的完整命令。例如pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128关键就是--index-url这个参数。它告诉 pip 不从 PyPI 装而是从 PyTorch 自己的软件仓库装这个仓库里才有针对特定 CUDA 版本预编译好的 GPU 版。4.2 conda 环境强烈建议先建一个独立环境再装我几乎不会在系统级的 Python 环境里直接装 PyTorch。因为不同项目的依赖经常会打架——有的项目要 PyTorch 1.13有的要 2.3有的要 cu118有的要 cu124全放在一个环境里早晚出问题。用 conda 建一个专门的环境conda create -n pytorch python3.10 conda activate pytorch这里的 Python 版本也不是随便选的。PyTorch 对 Python 版本有严格的预编译范围最新的 PyTorch 2.x 支持 Python 3.8-3.12但部分老版本只支持到 3.10。如果你不确定选 Python 3.10 是最稳的几乎所有 PyTorch 版本都兼容。接着在激活的环境里执行官网生成的安装命令。需要注意如果用 conda 安装 PyTorch 全家桶官网给的命令是conda install pytorch torchvision torchaudio pytorch-cuda12.1 -c pytorch -c nvidia这个命令会从pytorch和nvidia两个 channel 拉包。国内如果网络不好经常会下载到一半失败或者速度奇慢。我的做法是优先用 pip 命令因为 PyTorch 的 pip 源通常比 conda 源更快更稳定而且 pip 方式的版本更新也更快。4.3 安装后验证 GPU 是否真正可用装完先别急着开始训练模型用一个三段式的脚本验证环境import torch # 1. CUDA 是否可用 print(CUDA available:, torch.cuda.is_available()) # 2. 有多少张卡 print(GPU count:, torch.cuda.device_count()) # 3. cuDNN 是否可用 print(cuDNN enabled:, torch.backends.cudnn.is_available()) print(cuDNN version:, torch.backends.cudnn.version())如果输出CUDA available: True说明你已经成功打通了 CUDA PyTorch 的链路。更深入的验证是实际跑一个小张量计算让 GPU 真刀真枪工作import torch # 打印 GPU 名称 print(GPU name:, torch.cuda.get_device_name(0)) # 创建一个在 GPU 上的随机 tensor x torch.rand(3, 3).cuda() y torch.rand(3, 3).cuda() z x y print(Matmul result:\n, z) # 一个基本的性能对比 import time n 5000 a_cpu torch.rand(n, n) b_cpu torch.rand(n, n) start time.time() _ a_cpu b_cpu print(fCPU matmul time: {time.time() - start:.4f}s) a_gpu a_cpu.cuda() b_gpu b_cpu.cuda() start time.time() _ a_gpu b_gpu torch.cuda.synchronize() print(fGPU matmul time: {time.time() - start:.4f}s)GPU 矩阵乘法的速度一般比 CPU 快几十倍。如果你看到 GPU 时间比 CPU 还慢或者报错AssertionError: Torch not compiled with CUDA enabled那基本可以断定装的还是 CPU 版回去把安装命令的--index-url参数补上重装一遍。4.4 常见报错的快速定位我把几个高频的 PyTorch 安装报错整理了一下每个都标了定位方向报错信息原因解决办法Torch not compiled with CUDA enabled装了 CPU 版重装带 index-url 的 GPU 版CUDA error: no kernel image is available for execution on the device显卡算力不在 PyTorch 编译支持列表里换更新的 CUDA 版本和 PyTorch 版本ImportError: DLL load failedWindows 上缺 cuDNN 的 DLL确认bin目录里有 cudnn*.dllRuntimeError: Found no NVIDIA driver on your system驱动没装或驱动报错执行nvidia-smi确认驱动状态OutOfMemoryErrorGPU 显存不够不是环境问题减小 batch size别瞎重装环境5. 多版本共存一台机器上同时装 CUDA 11.8 和 12.85.1 为什么要搞多版本深度学习社区里有一个很现实的情况很多论文的官方代码仓库用的是老环境比如某个复现项目是 2023 年写的固定用 CUDA 11.8 PyTorch 1.13而你现在的新项目要用 CUDA 12.8 PyTorch 2.5。让它们同时共存一台机器是完全合理的需求。方案其实不复杂CUDA Toolkit 本身就支持多版本共存因为安装器会把不同版本安装到不同的目录。Windows 下默认分别是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8和...\v12.8Linux 下默认是/usr/local/cuda-11.8和/usr/local/cuda-12.8。问题在于PATH环境变量一次只能指向其中一个路径的bin目录。所以切换 CUDA 版本这个操作本质上是修改PATH和LD_LIBRARY_PATH的指向。5.2 Linux 下用软链接切换版本Linux 下我比较推荐用软链接管理。假设你装了 11.8 和 12.8 两个版本系统里通常有一个默认的/usr/local/cuda软链接安装时选择创建符号链接就会生成。切换版本的命令# 切到 11.8 sudo rm -f /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda # 切到 12.8 sudo rm -f /usr/local/cuda sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda这样改完之后/usr/local/cuda/bin就会跟随软链接指向当前版本。由于PATH里写的是/usr/local/cuda/bin而不是/usr/local/cuda-12.8/bin所有编译工具就会自动找到切换后的版本。但这里有个细节nvcc -V输出的是nvcc这个编译器的版本它由PATH里的路径决定。如果你已经执行了上面的软链接切换但nvcc -V还是老版本可以执行which nvcc看看实际指向。如果是/usr/local/cuda/bin/nvcc说明软链接生效了可能是 shell 缓存了旧路径执行hash -r刷新一下。5.3 conda 环境里完成版本隔离对于 PyTorch 用户来说我强烈建议把 conda 环境作为版本隔离的主力CUDA Toolkit 的软链接切换作为辅助。因为很多时候同一个项目里既要用 PyTorch 的 GPU 版本又要编译一些自定义 CUDA 算子比如某些第三方的CUDA extension这时候必须保证nvcc的版本和 PyTorch 编译支持的 CUDA 版本一致。我的典型做法是系统层面默认安装 CUDA 12.8日常主力。conda 建一个pytorch_cu124环境里面按官网命令装上 cu124 的 PyTorch。某些老项目需要 CUDA 11.8 时用软链接切一下系统默认版本再在 conda 环境里装pytorch-cuda11.8。这里注意conda 会自动在环境内部安装一套独立的 CUDA 运行时库所以即使系统层面的nvcc是 12.8conda 环境里的 PyTorch 依然可以使用它自己捆绑的 CUDA 运行时。只有当你要从源码编译 CUDA 扩展时才需要让nvcc版本和 PyTorch 的预编译目标匹配。5.4 电脑迁移或者拷贝环境的最佳姿势热搜词里有一个是cuda 迁移我猜测是很多人换了电脑后直接把旧机器的 conda 环境整个拷贝到新机器结果运行各种报错。这里把正确姿势说一下。conda 环境本身跨电脑迁移是可以的但是它依赖的底层 CUDA 版本是绑定的。如果旧机器是 CUDA 11.8新机器装的是 CUDA 12.8那么直接把整个site-packages拷过来必然出问题。正确迁移流程在旧环境中执行pip freeze requirements.txt。在新机器上建一个同样 Python 版本的 conda 环境。根据新机器的驱动和 CUDA 版本重新从 PyTorch 官网生成对应版本的 pip 安装命令。先装 PyTorch 全家桶再执行pip install -r requirements.txt。如果是离线环境需要提前下载好所有 wheel 包然后用pip download和pip install --no-index --find-links来离线安装。如果没条件离线安装那还是通过联网环境逐个装更稳。6. 安装完成后的体检清单几条我用着非常顺手的命令装完所有东西以后我建议按顺序跑一遍下面的检查确保链路没有隐藏问题。第一步确认基础驱动nvidia-smi输出正常会显示显卡型号、驱动版本、显存占用以及右上角的 CUDA 支持版本。如果报错找不到nvidia-smi说明驱动没装好后面都不用看了。第二步确认编译器版本nvcc -V如果显示command not found检查环境变量。如果显示出版本号但与nvidia-smi里的 CUDA 版本不一致只要前者不高于后者就没问题。第三步确认 cuDNN 版本Windows 用where cudnn64_9.dllLinux 用cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2确认文件存在且路径正确。第四步确认 PyTorch 的 GPU 可用性python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0)); print(torch.backends.cudnn.version())这几条命令输出各自的作用分别是确认 PyTorch 版本、确认 CUDA 通道是否打开、确认具体显卡型号、确认 cuDNN 的版本号。把这个组合命令保存成一个 shell 脚本或者别名以后每次换环境、换机器一条命令就能完成体检省去很多排查时间。第六步可选确认扩展库的算力识别如果你要用的深度学习扩展库比如 FlashAttention、SageAttention报错提示算力识别不了那就去检查 PyTorch 是否支持你的显卡架构以及安装在的 CUDA 版本是否包含对应的sm_xx编译目标。最直接的排查方法import torch print(torch.cuda.get_device_capability())输出像(8, 9)这样的元组代表算力 8.9。如果这个输出和扩展库要求的算力不匹配那就是版本选择的问题回去换合适的 PyTorch 版本。按照这套流程走下来一套干净、可用、性能达标的 CUDA cuDNN PyTorch 环境基本就齐了。最后再说一个我实测很管用的小技巧凡是装深度学习环境所有安装包优先从官方渠道下载所有环境变量都写到用户级配置里所有依赖都锁版本。这三个所有帮我省掉了无数重复排查的时间希望你以后也能少踩几个坑。
CUDA与cuDNN安装全攻略：从驱动到PyTorch的版本匹配与验证
从装好 GPU 驱动到跑通torch.cuda那一步中间踩的坑比想象中多得多。很多人卡在一个很奇怪的位置驱动装了CUDA 装了PyTorch 也能import但一跑模型风扇就是不转控制台默默提示Using CPU。查了半天才发现要么是 CUDA 版本和 PyTorch 的预编译版本对不上要么是 cuDNN 放错了目录根本没生效。这篇就从头到尾把 CUDA cuDNN PyTorch 的安装链路理一遍Windows 和 Linux 都会讲到重点放在版本匹配逻辑和装完之后的验证方法上。1. 动手前先搞清版本匹配否则后面全白搭1.1 显卡驱动和 CUDA Toolkit 到底是什么关系先说一个最常见的误区很多人以为装了显卡驱动就等于装了 CUDA然后直接跑nvcc -V发现命令不存在就慌了。实际上这两件事是分开的。NVIDIA 显卡驱动是让系统能识别并调用 GPU 的底层程序而 CUDA Toolkit 是给开发者用的编译器和库集合。你可以把驱动理解成硬件能用CUDA Toolkit 理解成软件能跑。驱动里面其实自带了一个运行时版的 CUDA 库这就是为什么你在命令行敲nvidia-smi右上角会显示一个CUDA Version: 12.8。这个版本号指的是当前驱动支持的最高 CUDA 版本不代表你已经安装了完整工具链。判断一块显卡支持到什么程度直接看nvidia-smi的输出--------------------------------------------------------------------------------------- | NVIDIA-SMI 545.84 Driver Version: 545.84 CUDA Version: 12.3 | ---------------------------------------------------------------------------------------上面这行信息意味着你的驱动最多能跑 CUDA 12.3 及以下版本的程序但你现在这个机器上不一定装了 CUDA Toolkit 12.3。这里引出一个重要操作原则先装驱动后装 CUDA Toolkit再装 cuDNN最后装 PyTorch顺序不要反。驱动是整个链路的底层支撑其他所有组件都是基于它运行的。1.2 算力和 CUDA 版本的对应关系4060 Ti 用户尤其注意GPU 有一个叫算力Compute Capability的东西用CC表示格式是8.6、8.9、9.0这种。PyTorch 和 cuDNN 在编译和运行时会针对不同算力做优化。如果驱动的 CUDA 版本太老不认新显卡的算力那 PyTorch 编译出来的一些算子就加载不上最终表现为各种诡异的报错比如no kernel image is available for execution on the device。以下是常见 N 卡架构和对应的算力、最低 CUDA 版本支持GPU 架构代表显卡算力最低驱动版本约建议 CUDA ToolkitAmpereRTX 30 系8.647011.x / 12.xAda LovelaceRTX 40 系8.952511.8 / 12.xHopperH1009.052512.xTuringRTX 20 系 / GTX 16 系7.541810.x / 11.xBlackwellRTX 50 系12.0 / 12.155012.8 / 13.xRTX 4060 Ti 是 Ada Lovelace 架构算力 8.9.这卡有个微妙的地方它最低能跑 CUDA 11.8但部分 PyTorch 的cu118预编译包里默认的算子编译目标只到安培架构的 8.6虽然后续补了sm_89的支持但你会发现有些手动编译的扩展比如某些自定义算子、SageAttention 这类优化库在编译时如果检测不到算力信息就会直接报could not determine cuda architec这类错误。我的建议是2024 年以后的新机器直接上 CUDA 12.x不要去碰 11.x。12.x 对 Ada 架构的适配更完整而且 PyTorch 官方对cu121、cu124、cu126、cu128这些版本的预编译包支持是最积极的。1.3 用 PyTorch 官网的版本表反推出你要装什么PyTorch 官方提供了一个非常关键的页面https://pytorch.org/get-started/locally/。你在这个页面选择你的操作系统、包管理器、CUDA 版本它会自动生成对应的安装命令。但要注意一个反直觉的点官网生成的命令不一定是你能用的。比如它默认会给你一个pip install torch torchvision torchaudio不带任何 CUDA 的--index-url参数。如果你直接复制这条命令很有可能会从 PyPI 装到 CPU 版或者装到一个和你驱动不匹配的旧版。正确做法是先在页面 CUDA 版本选项里明确选择一个通常是12.1、12.4或12.8然后复制带--index-url的那条命令。这件事后面第四章我会详细拆。版本匹配的整个逻辑链其实就一句话驱动版本 ≥ CUDA Toolkit 版本 ≥ PyTorch 预编译版本 ≥ cuDNN 依赖的 CUDA 版本。只要这条链路不乱后面基本稳。2. 动手装 CUDAWindows 和 Linux 各有各的坑2.1 Windows 下安装 CUDA Toolkit 的正确姿势Windows 下安装 CUDA 核心就是去 NVIDIA 官网的CUDA Toolkit下载页面选版本、选操作系统、选安装包类型。这里有几个关键选择要注意下载方式的选择exe (local)本地安装包离线安装体积大2-3GB但是安装过程最稳定。exe (network)网络版安装包体积小但安装时会实时从服务器拉取文件网络不稳定容易失败。我的建议是用 local 版本。虽然下载时间长一点但省去安装过程中断重来的痛苦。安装过程的关键选项双击安装后在选择安装类型界面选自定义而不是精简。因为精简安装会默认把 NVIDIA 显卡驱动也重新装一遍这是很多环境被搞坏的原因——你用精简安装覆盖了原驱动结果装完nvidia-smi显示版本变了部分老项目开始报驱动版本太低。在自定义安装的组件列表中你会看到CUDA里面包含 Runtime、Development、Visual Studio Integration 等子项Driver components这个一定要取消勾选除非你的驱动版本比这个还老其他附加组件这里有一个常见报错在 Windows 上安装时弹出CUDA Visual Studio Integration ... no supported version of Visual Studio was found很多人在这一步感觉天塌了以为安装失败了。实际上这个报错只影响你在 Visual Studio 里用 CUDA 的图形化调试插件不影响命令行编译 CUDA 程序也不影响 PyTorch 调用 GPU。如果你不写 C 的 CUDA 扩展完全可以忽略这个警告继续安装。装完之后nvcc -V就能用了。但注意如果nvcc -V报不是内部或外部命令说明环境变量没配好。CUDA 安装器默认会自动添加环境变量但有时因为路径里包含空格或者安装目录被修改会导致环境变量不生效。检查系统环境变量里的Path确认是否包含以下几条C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\binC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\libnvvpC:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\extras\CUPTI\lib64C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include如果你安装的时候自定义了路径就按实际路径改。改完环境变量之后新开的命令行窗口才会生效。2.2 Linux 下 .run 文件安装及 gzip 报错处理Linux 环境下装 CUDA我推荐用.run文件而不是 deb 包。.run文件可以指定安装目录方便多版本共存而且对系统自带的驱动影响小。下载页面里选runfile (local)即可。拿到.run文件后先不要急着执行我这里有个血泪教训。很多人直接跑sudo sh cuda_12.8.0_560.28.03_linux.run然后报一个极其诡异的错误gzip: stdin: invalid compressed>sudo sh cuda_12.8.0_560.28.03_linux.run --tmpdir/home/username/tmp执行之后会进入一个字符交互界面。第一个问题问是否安装 NVIDIA Accelerated Graphics Driver for Linux一定要选 No。因为服务器或者个人机器上的显卡驱动一般都提前装好了重复安装驱动轻则覆盖驱动导致nvidia-smi失效重则因为和内核版本不匹配导致黑屏。剩下的选项CUDA Toolkit 选 YesCUDA Samples 可以根据需要选符号链接symlink建议选 Yes这样/usr/local/cuda会指向你刚装的这个版本后续很多编译工具默认找这个路径。安装完成后把 CUDA 相关的路径加入环境变量编辑~/.bashrcexport PATH/usr/local/cuda/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda/lib64:$LD_LIBRARY_PATH保存后执行source ~/.bashrc然后nvcc -V检查是否生效。2.3 nvcc -V 和 nvidia-smi 版本不一致是正常现象装完 CUDA 后你在终端跑nvcc -V可能显示 12.8跑nvidia-smi显示CUDA Version: 12.8但这个正常的版本一致有时不会发生——比如nvcc -V显示 12.4nvidia-smi显示 12.8这不是故障。nvidia-smi里的CUDA Version指的是驱动能支持的最高版本nvcc -V里的release指的是编译器实际使用的版本。打个比方驱动是一个平台它可以承载比你当前装的更低版本的 CUDA但你实际编译程序用的版本由nvcc决定。所以只要满足驱动的 CUDA 支持版本 ≥ nvcc 的版本那这套环境就是可用的。如果你发现nvidia-smi显示 12.8nvcc -V显示 12.4完全不用慌先用 12.4 干活就行。只有当nvcc -V的版本比驱动支持的还高时才需要去升级驱动或降低 CUDA Toolkit 版本。3. cuDNN 安装本质就是复制文件但复制错了地方等于白装3.1 cuDNN 到底是什么东西cuDNNCUDA Deep Neural Network library是 NVIDIA 专门为深度学习设计的一个高性能加速库里面用深度优化的矩阵乘法和卷积实现把 GPU 的计算潜力榨干。PyTorch 在 GPU 上跑卷积神经网络时底层大量调用的就是 cuDNN 的算子。严格来说PyTorch 的预编译包里已经内置了一部分 cuDNN 的运行时库。所以有些人没装 cuDNNPyTorch 照样能跑起来。但这里有个性能隐患内置的版本可能比较旧某些新型卷积算子的性能不是最优的。另外如果你想编译 TensorFlow 或其他需要显式链接 cuDNN 的框架就必须自己装 cuDNN。cuDNN 的版本编号中间也有门道。之前 cuDNN 8.x 对应 CUDA 11.xcuDNN 9.x 对应 CUDA 12.x。下载时一定要对应上 CUDA 版本。比如你已经装了 CUDA 12.8那就应该下载 cuDNN 9.x for CUDA 12.x。cuDNN 下载页面会让你先注册登录后选择匹配的版本。3.2 Windows 下 cuDNN 安装三个目录的规则Windows 下解压 cuDNN 的压缩包你会看到里面有三个文件夹bin、include、lib。所谓的安装就是把这三个文件夹里的文件分别复制到 CUDA 安装目录对应的同名文件夹里。具体来说把解压后的bin\cudnn*.dll复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\bin把解压后的include\cudnn*.h复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\include把解压后的lib\x64\cudnn*.lib复制到C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.8\lib\x64这个复制过程的原理其实很简单CUDA 的编译器在编译程序时会去include目录找头文件运行时去bin目录找 DLL 动态链接库链接时去lib\x64目录找.lib静态导入库。三个目录各管一摊少一个都会出问题。最容易犯的错是只复制了include和lib忘了把bin下的 DLL 复制过去。结果编译时一切正常一运行就报DLL load failed或者error while loading shared libraries这就是典型的编译能找到头文件但运行时找不到动态库。我常用的验证方法是打开命令行进入到包含cudnn_ops_train64_9.dll的目录也就是 CUDA 的 bin 目录然后执行where cudnn64_9.dll正常情况下能返回完整路径。如果不能返回说明bin目录里的文件没复制到位或者环境变量没配好这就相当于 cuDNN 没装上。3.3 Linux 下 cuDNN 安装与验证Linux 下 cuDNN 离线包一般是.tar.gz格式。下载解压后同样是把对应文件复制到 CUDA 目录里tar -xzvf cudnn-linux-x86_64-9.5.0.50_cuda12-archive.tar.xz cd cudnn-linux-x86_64-9.5.0.50_cuda12-archive sudo cp include/cudnn*.h /usr/local/cuda/include/ sudo cp lib/libcudnn* /usr/local/cuda/lib64/ sudo chmod ar /usr/local/cuda/include/cudnn*.h /usr/local/cuda/lib64/libcudnn*最后这个chmod ar很重要否则非 root 用户编译时没有权限读取这些文件会报Permission denied。装完以后查询 cuDNN 版本我一般用两种方式看文件内容cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2如果文件不存在说明头文件复制路径不对。编译官方测试样例cp -r /usr/local/cuda/samples /home/username/cuda_samples cd /home/username/cuda_samples/1_Utilities/deviceQuery make ./deviceQuery这个deviceQuery会输出显卡详细信息如果最后一行显示Result PASS说明 CUDA 本身没问题。想测 cuDNN 的话看simpleConvolution那个样例它能跑通就意味着 cuDNN 的库链路是通的。4. PyTorch 安装一个参数之差CPU 版和 GPU 版天壤之别4.1 为什么 pip 默认装的是 CPU 版PyTorch 在 PyPI 上长期存在的默认版本是 CPU 版。也就是说如果你直接执行pip install torch装下来的是只能跑 CPU 的版本完全用不上显卡。这事让很多人栽过跟头看到官网命令是pip install torch torchvision torchaudio复制下来就装装完进 Python 跑torch.cuda.is_available()一直返回False其实原因是这个默认命令根本没有指定 CUDA 编译版本。正确的做法是从 PyTorch 官网的左下角选好操作系统、包管理器、CUDA 版本然后复制生成的那条带--index-url的完整命令。例如pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128关键就是--index-url这个参数。它告诉 pip 不从 PyPI 装而是从 PyTorch 自己的软件仓库装这个仓库里才有针对特定 CUDA 版本预编译好的 GPU 版。4.2 conda 环境强烈建议先建一个独立环境再装我几乎不会在系统级的 Python 环境里直接装 PyTorch。因为不同项目的依赖经常会打架——有的项目要 PyTorch 1.13有的要 2.3有的要 cu118有的要 cu124全放在一个环境里早晚出问题。用 conda 建一个专门的环境conda create -n pytorch python3.10 conda activate pytorch这里的 Python 版本也不是随便选的。PyTorch 对 Python 版本有严格的预编译范围最新的 PyTorch 2.x 支持 Python 3.8-3.12但部分老版本只支持到 3.10。如果你不确定选 Python 3.10 是最稳的几乎所有 PyTorch 版本都兼容。接着在激活的环境里执行官网生成的安装命令。需要注意如果用 conda 安装 PyTorch 全家桶官网给的命令是conda install pytorch torchvision torchaudio pytorch-cuda12.1 -c pytorch -c nvidia这个命令会从pytorch和nvidia两个 channel 拉包。国内如果网络不好经常会下载到一半失败或者速度奇慢。我的做法是优先用 pip 命令因为 PyTorch 的 pip 源通常比 conda 源更快更稳定而且 pip 方式的版本更新也更快。4.3 安装后验证 GPU 是否真正可用装完先别急着开始训练模型用一个三段式的脚本验证环境import torch # 1. CUDA 是否可用 print(CUDA available:, torch.cuda.is_available()) # 2. 有多少张卡 print(GPU count:, torch.cuda.device_count()) # 3. cuDNN 是否可用 print(cuDNN enabled:, torch.backends.cudnn.is_available()) print(cuDNN version:, torch.backends.cudnn.version())如果输出CUDA available: True说明你已经成功打通了 CUDA PyTorch 的链路。更深入的验证是实际跑一个小张量计算让 GPU 真刀真枪工作import torch # 打印 GPU 名称 print(GPU name:, torch.cuda.get_device_name(0)) # 创建一个在 GPU 上的随机 tensor x torch.rand(3, 3).cuda() y torch.rand(3, 3).cuda() z x y print(Matmul result:\n, z) # 一个基本的性能对比 import time n 5000 a_cpu torch.rand(n, n) b_cpu torch.rand(n, n) start time.time() _ a_cpu b_cpu print(fCPU matmul time: {time.time() - start:.4f}s) a_gpu a_cpu.cuda() b_gpu b_cpu.cuda() start time.time() _ a_gpu b_gpu torch.cuda.synchronize() print(fGPU matmul time: {time.time() - start:.4f}s)GPU 矩阵乘法的速度一般比 CPU 快几十倍。如果你看到 GPU 时间比 CPU 还慢或者报错AssertionError: Torch not compiled with CUDA enabled那基本可以断定装的还是 CPU 版回去把安装命令的--index-url参数补上重装一遍。4.4 常见报错的快速定位我把几个高频的 PyTorch 安装报错整理了一下每个都标了定位方向报错信息原因解决办法Torch not compiled with CUDA enabled装了 CPU 版重装带 index-url 的 GPU 版CUDA error: no kernel image is available for execution on the device显卡算力不在 PyTorch 编译支持列表里换更新的 CUDA 版本和 PyTorch 版本ImportError: DLL load failedWindows 上缺 cuDNN 的 DLL确认bin目录里有 cudnn*.dllRuntimeError: Found no NVIDIA driver on your system驱动没装或驱动报错执行nvidia-smi确认驱动状态OutOfMemoryErrorGPU 显存不够不是环境问题减小 batch size别瞎重装环境5. 多版本共存一台机器上同时装 CUDA 11.8 和 12.85.1 为什么要搞多版本深度学习社区里有一个很现实的情况很多论文的官方代码仓库用的是老环境比如某个复现项目是 2023 年写的固定用 CUDA 11.8 PyTorch 1.13而你现在的新项目要用 CUDA 12.8 PyTorch 2.5。让它们同时共存一台机器是完全合理的需求。方案其实不复杂CUDA Toolkit 本身就支持多版本共存因为安装器会把不同版本安装到不同的目录。Windows 下默认分别是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8和...\v12.8Linux 下默认是/usr/local/cuda-11.8和/usr/local/cuda-12.8。问题在于PATH环境变量一次只能指向其中一个路径的bin目录。所以切换 CUDA 版本这个操作本质上是修改PATH和LD_LIBRARY_PATH的指向。5.2 Linux 下用软链接切换版本Linux 下我比较推荐用软链接管理。假设你装了 11.8 和 12.8 两个版本系统里通常有一个默认的/usr/local/cuda软链接安装时选择创建符号链接就会生成。切换版本的命令# 切到 11.8 sudo rm -f /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda # 切到 12.8 sudo rm -f /usr/local/cuda sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda这样改完之后/usr/local/cuda/bin就会跟随软链接指向当前版本。由于PATH里写的是/usr/local/cuda/bin而不是/usr/local/cuda-12.8/bin所有编译工具就会自动找到切换后的版本。但这里有个细节nvcc -V输出的是nvcc这个编译器的版本它由PATH里的路径决定。如果你已经执行了上面的软链接切换但nvcc -V还是老版本可以执行which nvcc看看实际指向。如果是/usr/local/cuda/bin/nvcc说明软链接生效了可能是 shell 缓存了旧路径执行hash -r刷新一下。5.3 conda 环境里完成版本隔离对于 PyTorch 用户来说我强烈建议把 conda 环境作为版本隔离的主力CUDA Toolkit 的软链接切换作为辅助。因为很多时候同一个项目里既要用 PyTorch 的 GPU 版本又要编译一些自定义 CUDA 算子比如某些第三方的CUDA extension这时候必须保证nvcc的版本和 PyTorch 编译支持的 CUDA 版本一致。我的典型做法是系统层面默认安装 CUDA 12.8日常主力。conda 建一个pytorch_cu124环境里面按官网命令装上 cu124 的 PyTorch。某些老项目需要 CUDA 11.8 时用软链接切一下系统默认版本再在 conda 环境里装pytorch-cuda11.8。这里注意conda 会自动在环境内部安装一套独立的 CUDA 运行时库所以即使系统层面的nvcc是 12.8conda 环境里的 PyTorch 依然可以使用它自己捆绑的 CUDA 运行时。只有当你要从源码编译 CUDA 扩展时才需要让nvcc版本和 PyTorch 的预编译目标匹配。5.4 电脑迁移或者拷贝环境的最佳姿势热搜词里有一个是cuda 迁移我猜测是很多人换了电脑后直接把旧机器的 conda 环境整个拷贝到新机器结果运行各种报错。这里把正确姿势说一下。conda 环境本身跨电脑迁移是可以的但是它依赖的底层 CUDA 版本是绑定的。如果旧机器是 CUDA 11.8新机器装的是 CUDA 12.8那么直接把整个site-packages拷过来必然出问题。正确迁移流程在旧环境中执行pip freeze requirements.txt。在新机器上建一个同样 Python 版本的 conda 环境。根据新机器的驱动和 CUDA 版本重新从 PyTorch 官网生成对应版本的 pip 安装命令。先装 PyTorch 全家桶再执行pip install -r requirements.txt。如果是离线环境需要提前下载好所有 wheel 包然后用pip download和pip install --no-index --find-links来离线安装。如果没条件离线安装那还是通过联网环境逐个装更稳。6. 安装完成后的体检清单几条我用着非常顺手的命令装完所有东西以后我建议按顺序跑一遍下面的检查确保链路没有隐藏问题。第一步确认基础驱动nvidia-smi输出正常会显示显卡型号、驱动版本、显存占用以及右上角的 CUDA 支持版本。如果报错找不到nvidia-smi说明驱动没装好后面都不用看了。第二步确认编译器版本nvcc -V如果显示command not found检查环境变量。如果显示出版本号但与nvidia-smi里的 CUDA 版本不一致只要前者不高于后者就没问题。第三步确认 cuDNN 版本Windows 用where cudnn64_9.dllLinux 用cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR -A 2确认文件存在且路径正确。第四步确认 PyTorch 的 GPU 可用性python -c import torch; print(torch.__version__); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0)); print(torch.backends.cudnn.version())这几条命令输出各自的作用分别是确认 PyTorch 版本、确认 CUDA 通道是否打开、确认具体显卡型号、确认 cuDNN 的版本号。把这个组合命令保存成一个 shell 脚本或者别名以后每次换环境、换机器一条命令就能完成体检省去很多排查时间。第六步可选确认扩展库的算力识别如果你要用的深度学习扩展库比如 FlashAttention、SageAttention报错提示算力识别不了那就去检查 PyTorch 是否支持你的显卡架构以及安装在的 CUDA 版本是否包含对应的sm_xx编译目标。最直接的排查方法import torch print(torch.cuda.get_device_capability())输出像(8, 9)这样的元组代表算力 8.9。如果这个输出和扩展库要求的算力不匹配那就是版本选择的问题回去换合适的 PyTorch 版本。按照这套流程走下来一套干净、可用、性能达标的 CUDA cuDNN PyTorch 环境基本就齐了。最后再说一个我实测很管用的小技巧凡是装深度学习环境所有安装包优先从官方渠道下载所有环境变量都写到用户级配置里所有依赖都锁版本。这三个所有帮我省掉了无数重复排查的时间希望你以后也能少踩几个坑。
