CUDA、cuDNN、PyTorch 版本搭配与深度学习环境搭建指南

深度学习环境搭建这件事说难不难说简单也真能把人熬到后半夜。我前后在十几台机器上折腾过 CUDA、cuDNN 和 PyTorch 的组合从笔记本上的入门卡到机房里插满的服务器踩过的坑基本可以凑成一本小册子。最典型的一次是帮朋友在他的工作站上装环境显卡是当时挺新的一张卡PyTorch 装上去也显示True结果一跑卷积就报no kernel image is available翻了两天才发现是编译时没有带上他这张卡的算力架构。这个问题的根源就是标题里说的三个东西没有搭配好。这篇内容不打算给你背版本号那东西写出来第二天就可能过时。我想讲的是判断方法看到一张卡、一个驱动版本、一个 PyTorch 版本号你能不能在脑子里快速圈出哪些组合是可行的哪些是看着能装、装完就出事的。适合刚入门配环境的新手也适合需要维护多套环境、给团队做标准化镜像的老手。全文提到的所有版本对应关系以官方文档为准我讲的是怎么读、怎么推、怎么验证。1. 三套版本号各管一摊混在一起才叫麻烦很多人第一次配环境失败不是操作错了是从一开始就把三个版本号的角色搞混了。驱动版本、CUDA 版本、PyTorch 版本它们处在不同的层次上约束方向也不一样。搞清层次关系后面所有的判断都是顺水推舟。1.1 显卡驱动是天花板不是地板nvidia-smi右上角会打印一行CUDA Version: 12.4之类的信息。我见过太多人把这一行当成我装的 CUDA 版本其实它表达的是当前驱动能够支持的最高 CUDA 运行时版本也就是天花板。你实际装的 CUDA Toolkit 只要不高于这个数理论上都能跑起来。这个区别很关键。天花板意味着你可以向下兼容装 11.8、12.1 都行但如果你想装 12.6 而这个数字只有 12.4那就只能先升驱动。升驱动这件事在个人机器上问题不大在公司服务器上经常要走运维流程所以先看一眼这个数字能省掉很多来回。提示nvidia-smi显示的是驱动支持的 CUDA 上限nvcc --version显示的才是当前环境里实际安装的 CUDA Toolkit 版本。两者不一致是正常现象不是环境坏了。1.2 CUDA Toolkit 与运行时是两个东西同样叫 CUDA实际上至少存在三份驱动里内置的运行时、你手动装的 Toolkit、以及 PyTorch 安装包自带的运行时。它们可以同时存在并且版本互不相同。举个实际场景你系统里nvcc --version显示 11.8但torch.version.cuda打印出来是 12.1。这不冲突因为 pip 或 conda 安装的 PyTorch 轮子里已经打包了一份它自己需要的 CUDA 运行时库跑模型时用的是这一份跟系统里那个 Toolkit 关系不大。真正需要系统 Toolkit 的是你要自己编译 CUDA 扩展、编译带 GPU 支持的 OpenCV、或者搞一些自定义算子的时候。只做常规训练和推理很多时候你不用装 Toolkit只要驱动够新就行。这一点在服务器上尤其重要因为 Toolkit 装多了会把磁盘吃满。1.3 cuDNN 跟着 CUDA 走不跟着显卡走cuDNN 是 NVIDIA 做的深度神经网络加速库卷积、池化、归一化这些算子的高效实现都在里面。它的版本约束只看一件事配套的 CUDA 大版本。cuDNN 8.x 适用于 CUDA 11.xcuDNN 9.x 适用于 CUDA 12.x这个对应关系相对稳定。显卡型号对 cuDNN 的影响是间接的——它通过 CUDA 传递过来。所以你不需要为每一张卡找不同的 cuDNN只需要确定 CUDA 大版本然后挑对应的 cuDNN 版本就行。用 conda 装 PyTorch 的时候cudnn 作为依赖会被自动带上版本也是配好的。用 pip 装的时候cuDNN 库被打包在轮子里同样不用你操心。只有在手动编译场景下才需要自己去下载 cuDNN 的压缩包、解压、把文件复制到 CUDA 目录里。这个过程下面会展开讲。2. 从硬件倒推先圈出可行区间再谈版本网上大部分教程的写法是推荐一套组合然后让你照着装。这套组合通常没问题但换一张卡、换一台机器就未必适用。我更倾向于用倒推的方法先看硬件能把范围限到哪里剩下的选择空间就小很多了。2.1 算力等级比显存大小更影响兼容性挑卡的时候大家习惯看显存但配环境的时候更该看的是compute capability也就是算力等级。它决定了 PyTorch 编译出来的二进制里有没有包含适配你这张卡的机器码。架构代际算力等级常见型号举例Pascal6.0 / 6.1 / 6.2较早的一批计算卡和消费卡Volta7.0面向数据中心的一代Turing7.5带光追的消费卡与相应计算卡Ampere8.0 / 8.6 / 8.7覆盖了很大一批主流卡Ada Lovelace8.9较新的消费级卡Hopper9.0面向数据中心的新一代怎么查自己的卡一条命令python -c import torch; print(torch.cuda.get_device_capability())这会输出类似(8, 6)的元组。如果这个命令还没法跑那就先看nvidia-smi里的型号然后去查对应算力。关键在于PyTorch 每个版本默认编译支持的算力列表是变化的。新版本会砍掉对老架构的支持。如果你手上是一张比较老的卡装了最新的 PyTorch就可能出现能 import、能cuda.is_available()返回 True但真正跑算子时崩掉的情况。这就是开头提到的那个报错的来历。2.2 驱动版本换算 CUDA 上限的方法拿到nvidia-smi显示的 CUDA 版本后怎么确定能装哪个版本有个粗糙但好用的规则显示的版本是 12.x那你装 12.x 这一整个大版本基本都行甚至某些情况下可以装 12 系列里比你显示版本更高的因为存在小版本兼容机制。显示的版本是 11.x那你可以装 11.x 全系但不要往上跨到 12。显示的版本太低比如还是 10.x、11.0 这种说明驱动很旧了最好先升级驱动再往下走。还有一个容易忽略的点12.x 和 11.x 之间不存在向上兼容。驱动只支持到 11.8你硬装 CUDA 12.1 的 PyTorch会遇到找不到动态库的错误。这时候要么降 PyTorch 的 CUDA 版本要么升驱动没有第三条路。2.3 把候选范围缩小到两三个组合做完前两步你的选择空间就很窄了。比如卡是 Ampere 架构算力 8.6比较新绝大多数 PyTorch 版本都支持。驱动显示 CUDA 12.4那 11.8、12.1、12.4 都可以考虑。团队里其他人用的是 12.1而且有现成的镜像。那答案基本就是 12.1。在有约束的前提下跟随团队现有环境是成本最低的选择因为共享的代码、脚本、Dockerfile 都能复用不用为每个环境单独调试。反过来如果是个人机器、从零开始那就优先选 PyTorch 官方矩阵里标注为稳定、且对应 CUDA 版本离驱动上限有一两档余量的那个。留余量的好处是以后升一次驱动不会立刻打破你的环境。3. 读懂 PyTorch 那串版本号别被最新带偏PyTorch 官网的安装页面会给出一个选择器选完系统和包管理工具之后会出现一串安装命令。这串命令里藏着最多信息也最容易被忽略。3.1 cu118、cu121、cu124 分别代表什么这些后缀里的数字指的是这个轮子编译时链接的 CUDA 版本。cu121就是 CUDA 12.1cu124是 12.4cpu则是不带 GPU 支持的纯 CPU 版本。有个细节值得说这些轮子带的是 CUDA 运行时库不是完整 Toolkit。所以你的系统里即使没装 CUDA Toolkitpip install torch --index-url .../cu121之后照样能跑 GPU 训练只要有驱动。这一点对新手特别友好也是为什么现在配环境比几年前简单多了。但反过来说如果你需要nvcc来编译东西那就得另外装 Toolkit别指望轮子里有。3.2 为什么不建议一味追最新新版本带来的收益通常是新算子、新优化、对最新架构的支持。代价是生态里的其他东西可能还没跟上。我遇到过的具体问题包括某个第三方库只支持到某个 PyTorch 版本、某些自定义算子在新版本上编译不过、某些模型仓库的 requirements 写死了旧版本。判断方法很简单翻一遍你项目里要用到的关键依赖看看它们的版本约束。如果有个库写的是torch1.12,2.2那你选 2.2 以上就是在给自己找麻烦。对纯学习、跑通经典模型的场景选一个发布了一段时间、社区讨论比较充分的版本比选当天发布的最新版稳当得多。出了问题搜得到答案这一点在实际工作里价值很大。3.3 老卡和旧服务器怎么找历史版本PyTorch 官方提供了历史版本的安装命令归档页面其中列出了每个版本对应的各种 CUDA 组合。如果你需要装比较旧的版本可以照着那个页面里的命令来。不过更省事的办法是用 conda 的版本语法直接指定conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 pytorch-cuda11.8 -c pytorch -c nvidia这种写法把 PyTorch、torchvision、torchaudio 三者的版本一起锁定能避免版本不匹配。这三个包的版本是有对应关系的不能随便组合。装错了通常在 import 的时候就报错或者更隐蔽地在训练中途出问题。注意torchvision和torchaudio的版本必须和torch主版本对齐。比如 torch 2.1.x 一般配 torchvision 0.16.x。版本对不上的时候import torchvision 会直接告诉你期望哪个版本照着提示降级即可。4. conda 装还是 pip 装以及混装的代价这个问题被问得最多答案也不是非此即彼。两种方式各有适用场景真正要避开的是两种方式混着用。4.1 conda 路线的特点用 conda 装 PyTorch它会连 CUDA 运行时、cuDNN、MKL 这些底层依赖一起装进当前环境的目录里。好处是隔离得彻底指定了pytorch-cuda12.1之后这个环境里用的就是 12.1跟系统里装了什么完全无关。代价是下载体积大、解压时间长而且 conda 的依赖求解有时候会卡很久。在磁盘空间紧张的机器上每个环境都带一份 CUDA 库几个环境下来就是好几个 G。conda 路线的另一个优势是 cuDNN 版本可控。如果你需要复现某篇论文的精确数值把 cuDNN 版本也固定住是有意义的因为不同版本的 cuDNN 在某些算子上的实现确实会有细微差别。4.2 pip 路线的特点pip 装的是预编译好的 wheel体积相对小一些安装速度快而且版本更新通常比 conda 渠道更及时。CUDA 和 cuDNN 的库被打包在nvidia-*系列依赖里会一起装进 site-packages。命令大致是这样pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121这个写法的好处是显式指定了 CUDA 版本不会因为默认源的变化而装错。4.3 混装之后的典型症状混装指的是先用 conda 装了一个版本的 torch后来又用 pip 装了一遍或者反过来。结果是两套文件同时存在于环境里import 的时候加载哪一个取决于路径顺序非常难以预测。症状包括torch.version.cuda显示的值和你以为的不一样、cudnn.version()返回 None、明明装了 GPU 版却is_available()返回 False。这类问题排查起来非常耗时因为报错信息通常不指向真正的原因。我个人的处理原则很粗暴但有效一个环境只用一种包管理器装 PyTorch。要换方式就把环境删了重建。环境重建五分钟排查混装问题可能是一下午。如果确实需要清理可以这样确认当前 torch 是从哪来的python -c import torch; print(torch.__file__)看输出路径是在 conda 的 pkgs 目录下还是在 site-packages 里能大致判断出来源。5. 装完之后必须走完的四道自检装完不等于是装对。我见过太多次看起来装好了结果一跑就崩的情况。下面这四道检查从浅到深每一道都能拦住一类问题。5.1 第一道驱动与 Toolkit 的基本状态nvidia-smi nvcc --version第一条确认驱动正常、显卡被识别。第二条确认 Toolkit 是否安装以及版本。如果nvcc找不到说明没装 Toolkit这在纯 pip 场景下是正常的不影响跑模型。5.2 第二道Python 里把版本全打出来python -c import torch; print(torch.__version__); print(torch.version.cuda); print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))这条命令一次输出四个关键信息PyTorch 版本、它链接的 CUDA 版本、GPU 是否可用、识别到的显卡名字。四个都对上了基本盘就稳了。5.3 第三道真跑一次算子is_available()返回 True 并不代表万事大吉。前面提到的no kernel image问题在这一步才会暴露python -c import torch; atorch.randn(1000,1000,devicecuda); print((aa).sum().item())跑一个矩阵乘法能把 CUDA 核函数加载、内存拷贝这些环节全走一遍。这一步过了才算真的能用。5.4 第四道cuDNN 有没有被真正加载python -c import torch; print(torch.backends.cudnn.version()); print(torch.backends.cudnn.is_available())返回一个版本号而不是 None说明 cuDNN 可用。如果返回 NonePyTorch 会退回到原生实现速度会明显慢下来。这种情况在手动装 cuDNN 但路径没配好的时候经常出现。再补一个实用检查看看到底用的是哪套库python -c import torch.utils.cpp_extension as e; print(e.include_paths())输出的路径能告诉你 CUDA 头文件从哪来遇到编译类问题时很有用。6. 多版本共存别去动系统那一套真实工作里经常需要同时维护多个环境分别对应不同的 CUDA 版本。这时候最忌讳的做法是每次换版本都去改系统的软链接或者环境变量改来改去最后自己都忘了当前是什么状态。6.1 用环境变量切不要替换软链接系统级的 CUDA 装在/usr/local/cuda它通常是一个指向具体版本的软链接。有些教程告诉你去改这个软链接来切换版本。这个做法在单用户、单项目的机器上勉强能用但一旦有多个项目并行就会互相干扰。更稳的做法是每个项目用自己的 conda 或 venv 环境环境里面装自己需要的 CUDA 运行时。需要nvcc的时候通过环境变量在当前 shell 会话里临时指定export CUDA_HOME/usr/local/cuda-11.8 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH这几个变量只在当前终端生效开新终端就恢复原状。不会污染系统状态也不会影响别人。6.2 目录规划上留出清晰的结构如果确实需要在系统里装多个 Toolkit建议安装时就用带版本号的目录名比如/usr/local/cuda-11.8、/usr/local/cuda-12.1各自独立。安装脚本默认就会这么命名只要别手动去覆盖/usr/local/cuda这个软链接就行。然后给常用的组合写两个小脚本放在自己 home 目录下# use_cuda118.sh export CUDA_HOME/usr/local/cuda-11.8 export PATH$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH$CUDA_HOME/lib64:$LD_LIBRARY_PATH echo CUDA switched to 11.8用的时候source use_cuda118.sh即可。比记住一长串路径可靠得多。6.3 切换后确认生效的方法切完之后别急着编译先确认三件事which nvcc nvcc --version echo $LD_LIBRARY_PATHwhich nvcc应该指向你刚设的目录nvcc --version应该显示目标版本。这两条都对上了再往下做。我吃过一次亏是LD_LIBRARY_PATH里旧路径排在新路径前面导致运行时加载了旧版本的库编译能过但一跑就崩排查了很久。提示用ldd看一个可执行文件到底链接了哪些库是排查这类路径问题的利器。特别是编译 CUDA 扩展失败的时候ldd的输出经常能直接指出问题。7. 几个高频报错以及我实际的排查顺序报错信息是排查的起点但很多时候它指向的不是根因。下面这几个是我遇到频率最高的按从表象到根因的顺序写一下。7.1 解压时报 invalid compressed data错误长这样gzip: stdin: invalid compressed>export CUDA_LAUNCH_BLOCKING1但这个只是让报错更精确不解决问题。另一种方式是TORCH_CUDA_ARCH_LIST环境变量它影响的是编译行为对已经装好的二进制轮子无效。7.3 version mismatch 和 undefined symbolImportError: libcudart.so.12: cannot open shared object file或者ImportError: undefined symbol: cudnnGetVersion这两个的根因都在动态库版本不一致。可能是 Toolkit 和 PyTorch 要求的版本差太远也可能是LD_LIBRARY_PATH里混进了别的环境的库。排查链路我一般这么走ldd看 PyTorch 的_C扩展链接了哪些库路径对不对。echo $LD_LIBRARY_PATH看有没有多余路径特别是别的 conda 环境的路径。检查是不是在同一个环境里混装过 conda 和 pip 的 torch。确认驱动版本排除驱动太旧的情况。第 2 条是最容易被忽略的。很多人都不会主动去设LD_LIBRARY_PATH但某些 shell 配置文件、某些工具安装脚本会偷偷加进去后果就是所有环境都受影响。7.4 手动装 cuDNN 时的路径细节手动装 cuDNN 的流程是下载压缩包、解压、把include和lib64里的文件复制到 CUDA 目录。这一步有两个容易出错的地方。一是复制之后忘了改权限。库文件的读权限如果不对运行时加载会失败报错信息不会直观说是权限问题。加一句chmod r更稳妥。二是复制到了错误的 CUDA 目录。机器上有多套 CUDA 的时候很容易复制到/usr/local/cuda这个软链接指向的目录而不是你实际要用的那个版本目录。复制之前先用readlink -f /usr/local/cuda确认目标。注意cuDNN 的文件名里带主版本号比如libcudnn.so.9和libcudnn.so.9.x.x。复制之后建议检查软链接是否完整缺链接会导致加载失败。8. 一套可以照着走的搭建顺序前面讲的都是判断方法最后把整个流程串一遍。顺序很重要颠倒的话会多走很多弯路。8.1 为什么这个顺序不能乱正确的顺序是确认硬件和驱动 → 确定 CUDA 版本 → 确定 PyTorch 版本 → 创建隔离环境 → 安装 → 自检。如果先去装 PyTorch装完发现 CUDA 版本不合适那就得重装。如果先创建环境再定版本环境里的包可能又要清理。从硬件往上推每一步都在缩小范围不会有返工。另一个经常被忽视的点是先创建环境再装包。不要在 base 环境里装 PyTorchbase 环境污染之后很多工具会出问题而且很难恢复。8.2 完整命令清单以一台驱动支持到 CUDA 12.4、显卡是 Ampere 架构的机器为例走 conda 路线# 1. 创建独立环境指定 Python 版本 conda create -n dl_env python3.10 -y conda activate dl_env # 2. 安装 PyTorch 全家桶锁定 CUDA 版本 conda install pytorch torchvision torchaudio pytorch-cuda12.1 -c pytorch -c nvidia -y # 3. 自检 python -c import torch; print(torch.__version__, torch.version.cuda, torch.cuda.is_available()) python -c import torch; atorch.randn(500,500,devicecuda); print((aa).sum().item())走 pip 路线的话第二步换成pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121Python 版本我一般选 3.10 或 3.11。太新的版本有些库还没跟上太旧的又会在某些新特性上受限。3.10 目前是兼容性最好的区间之一。8.3 环境固化与迁移环境跑通之后立刻做两件事导出一份描述文件写一份简短的 README。导出conda env export --no-builds environment.yml pip freeze requirements.txt--no-builds的作用是去掉构建号这样在不同平台上恢复的时候兼容性更好。README 里至少写清楚三件事显卡型号、驱动版本、每个包的版本。看起来是小事但过半年之后你要在另一台机器上复现同样的环境这份记录能省掉大量时间。我现在的习惯是在项目根目录放一个env_notes.md把nvidia-smi的输出直接贴进去非常直观。如果团队规模大一些可以考虑直接用 Docker 把环境封起来。这时候environment.yml就成了 Dockerfile 的基础构建出来的镜像在不同机器上行为完全一致比手工配环境可靠得多。最后说一个我踩过好几次的坑不要在环境跑通之后立刻升级任何东西。有时候看到有新版本顺手conda update一下结果环境就坏了。跑通的环境就冻结住需要新版本的时候另开一个环境。环境是会越攒越多的但比起半夜被一个突然崩掉的环境打断工作多占几个 G 的磁盘实在不算什么。