Linux 上装 CUDA 与 cuDNN 本身不复杂，真正容易卡人的是思路没理顺。默认路径、指定路径、多版本共存——这些词看着普通，实际决定了后续是“环境在为你服务”还是“你天天为环境返工”。尤其一台机器既要跑老框架又要跑新模型时，装法和切换方案没选对，很容易陷入“改完一个版本又搞坏另一个”的循环。这篇指南把默认安装和指定安装两套路线都拆开讲，再把多 CUDA 环境一键切换的做法一并整理出来，适合所有需要自己维护 GPU 开发机的朋友，也适合刚入门、第一次面对nvcc和环境变量就发懵的新手。
1. 先想清楚装法，再想下载：默认路径与指定路径在决策层面的差异
很多教程会直接丢给你一条安装命令，让你一路 next，最后nvcc -V一输出就宣布胜利。可一旦你需要在两套 CUDA 之间来回切，这种方式就成了以后踩坑的根源。所以我建议先别急着下载安装包，先用十分钟想明白一个问题：你的机器上，未来大概率会存在几个 CUDA 环境？
1.1 默认路径方案在解决谁的痛点
默认路径方案指的是把 CUDA Toolkit 安装到/usr/local/cuda-<版本>，同时自动生成一个名为/usr/local/cuda的软链接指向具体版本。官方推荐做法通常基于这条路，因为大量软件、深度学习框架、编译脚本都会默认去/usr/local/cuda找头文件和库文件。
这个方案的最大价值是“省心”。它像一个固定在玄关的抽屉，里面只放一套工具，你每天出门不用思考今天钥匙在哪。适合哪些场景呢？单人开发机、专用训练服务器、或者的就是一台只跑一个固定框架、固定依赖的环境。在这种场景下，默认路径可以少写很多环境变量，也不用担心哪条路径写错导致程序找不到 CUDA 库。
但它的隐患也很明显：一旦你日后想装第二个版本，就要小心处理/usr/local/cuda这个软链接的指向。处理不当，编译老项目时nvcc是新版本，运行时却可能加载旧版本库，各种诡异报错随之而来。
1.2 指定路径方案在解决谁的痛点
指定路径方案是把 CUDA Toolkit 装到自定义目录，比如/opt/cuda/cuda-11.8、/opt/cuda/cuda-12.4，然后在环境变量层面管理到底用哪个。目录独立，互不覆盖，每个版本都像抽屉里单独分格放好的工具盒，需要哪套就把哪套拎出来。
这种方案适合多环境共存。我见过不少项目组，老代码基于 CUDA 11.8 和旧版框架，新模型又依赖 CUDA 12.x，如果共用一套环境，升级库名和 ABI 就可能让老代码编译失败。指定路径可以让你随时切换到项目最合适的版本，也更容易备份和回滚。
它的代价是你要对 PATH、LD_LIBRARY_PATH 这些东西有基本概念，还要接受“某些软件不会自动去自定义目录找 CUDA”的事实。后面我会专门讲怎么处理这种“识别不到自定义路径”的问题。
1.3 安装前必须确认的三件事
无论你选哪条路，动手前有三个事一定要确认清楚，否则装到一半很容易卡住。
第一是 GPU 算力。不同的显卡计算能力对应不同的 CUDA 版本限制，太老的卡装新版工具包可能根本无法运行。驱动自带的 GPU 状态工具、或者设备管理工具里通常能看到计算能力编号。以我的经验，至少要知道自己的卡属于哪一代，再决定选 CUDA 11 还是 CUDA 12 线。
第二是显卡驱动版本。CUDA 工具包本身是一个编译器加运行库的集合，它并不直接等同于驱动。驱动版本决定了你能运行多新的 CUDA runtime。装完工具包后如果运行样例报“驱动版本不足”，大概率是驱动太老，而不是工具包没装好。
第三是编译工具链。CUDA 编译器对 GCC 有版本上限要求，比如新版 CUDA 可能不支持系统默认的过新 GCC。装之前用gcc --version看一眼，如果版本超出官方支持范围，或者你想图省事，可以在安装时使用--override参数跳过检查，但我不建议拿核心环境开玩笑。更稳妥的办法是多版本 GCC 共存，编译时指定正确的编译器。
2. 默认/指定路径双方案的完整 CUDA 安装实录
确认了前面的基础条件，下面就是我比较推荐的标准操作流程。这里我以 runfile（.run）安装包为例，不用包管理器安装，主要原因是 runfile 跨发行版通用性最好，而且对安装目录有更高的控制权，不管默认路径还是指定路径都能覆盖。
2.1 下载后先做的校验
去 GPU 厂商的官方开发者平台下载 CUDA Toolkit 安装包时，选带linux、对应 CPU 架构、runfile关键字的文件。下载完成后不要急着执行，先做一步校验，用官方页面给出的 SHA256 值核对文件完整性。
wget <官方下载页复制出的.run链接> sha256sum cuda_12.4.0_550.54.15_linux.run把输出结果和官方页面上的值对一下，一致再继续。这一步不是走形式。网络传输中文件损坏的情况虽然不多，但一旦出现，即使安装器能跑完，后面也可能出现库文件计算不一致的奇怪问题。我见过有人跳过校验，安装完编译任何东西都报内存错误，最后重新对比校验才发现安装包本身就是坏的。
2.2 默认路径安装方案（装到 /usr/local）
如果前面判断下来，你这台机器未来基本只用一个 CUDA 版本，那么默认路径方案是最省事的。
sudo sh cuda_12.4.0_550.54.15_linux.run --toolkit --silent --override这里的--toolkit表示只装工具包，不装驱动和示例。大多数服务器场景，驱动早就装好了，如果让 runfile 连驱动一起装，很可能会覆盖掉驱动管理器的安装，重启后内核驱动模块反而不匹配。所以我的习惯是明确加--toolkit，只取我需要的编译器和运行库。
装完后系统会多出/usr/local/cuda-12.4目录，同时自动创建/usr/local/cuda软链接指向它。此时把环境变量固定指向/usr/local/cuda即可，以后切换版本时只需调整软链接，环境变量完全不用动。这套打法的好处就在这里，用户层面的 PATH 永远是稳定的。
2.3 指定路径安装方案（装到 /opt/cuda）
如果是多版本共存场景，我的建议是把每个版本装成完全独立的目录树，目录里就带版本号，永远不要互相覆盖。
sudo mkdir -p /opt/cuda sudo sh cuda_12.4.0_550.54.15_linux.run --toolkit --silent --override --installpath=/opt/cuda/cuda-12.4--installpath是 runfile 安装器自带的参数，后面接的路径就是你要把 CUDA 装到的目标目录。装完后检查一下/opt/cuda/cuda-12.4/bin/nvcc是否存在。第二个版本也照葫芦画瓢，把版本号换成 11.8，路径换成/opt/cuda/cuda-11.8，完全独立。
用一个我经常给朋友打的比方：默认路径像是系统里只有一个“默认浏览器”，你换了版本，所有调用都自动走后门；指定路径像是系统里装了好几个浏览器，你通过环境变量告诉程序“今天用哪个”。两者没有绝对的优劣，只有适不适合你的场景。
2.4 runfile 关键参数说明
很多人不知道 runfile 自己的参数到底影响什么，这里列几个我常用的：
--silent：静默安装，不弹出交互界面，适合批量部署。--toolkit：只安装 CUDA 工具包，不装驱动、不装示例。想省时间就加它。--installpath=<路径>：指定安装目录，自定义路径方案都要带。--override：跳过部分版本兼容性检查，比如编译器版本过高时的报错。能用但别滥用，它只是把警告压了下去，并不代表真的兼容。
我建议任何时候安装默认路径方案都不要忘记指定--toolkit，尤其是多人共用、别人已经维护好驱动的服务器，乱装驱动会把整个环境搞得一团糟。如果确实需要装示例，用--samples和--samplespath单独控制，示例不属于核心运行库，没必要挤进默认路径。
2.5 环境变量和库加载路径一次性配好
装完只是第一步，第二步是把环境变量配好。否则你输入nvcc时，系统还是不知道上哪找它。
在/etc/profile.d/下新建一个cuda.sh，写入下面内容；这样所有用户登录后都会加载：
export CUDA_HOME=/usr/local/cuda export PATH=$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH=$CUDA_HOME/lib64:${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}如果是指定路径方案，就把CUDA_HOME改成/opt/cuda/cuda-12.4之类。写完别忘执行source /etc/profile.d/cuda.sh或者重新登录终端。
还要让系统动态链接器知道 CUDA 的运行库在哪里，否则即使环境变量配了 LD_LIBRARY_PATH，某些服务场景下还是可能加载不上。做法是新建/etc/ld.so.conf.d/cuda.conf，内容写一行：
/usr/local/cuda/lib64然后执行sudo ldconfig。这样像 OpenCV、FFmpeg 这类依赖 CUDA 加速的软件，在系统层面就能找到库文件。
最后验证一把：
nvcc -V看到版本号输出，CUDA Toolkit 的部分就算装好了。
3. cuDNN 入库：tar 包方式与 deb 方式的选择
CUDA Toolkit 装好后，很多加速场景还差最后一个核心组件：cuDNN。这是一个深度神经网络加速库，官方提供多种安装形式，我推荐用 tar 包方式，尤其是你打算保持多版本共存时。
3.1 为什么我建议用 tar 包
官方通常给三种形式：deb 包、rpm 包、tar 包。deb 包安装快捷，但会直接把头文件和库文件放到系统目录里，和发行版包管理系统混在一起。如果你以后想换版本，卸载和回滚都麻烦，而且稍不注意就会覆盖当前正在使用的其他版本的库文件。
tar 包则是一个独立归档，解压后就是一个目录，你可以手动决定把文件放进哪个 CUDA 版本目录。它更像“复制粘贴式”的安装，看着原始，但可控性最高。我维护过的多 CUDA 机器上，cuDNN 基本都是 tar 包方式，配合指定路径的 CUDA，互不干扰。
3.2 下载、解压、拷贝三步走
前往 GPU 厂商官方开发者平台，选 cuDNN 下载区，选择“Linux 平台、x86 架构、tar 包”格式。注意看清两个匹配信息：CUDA 版本、cuDNN 版本。以 CUDA 12.x 为例，下载文件名通常带cuda12关键字。
下载后解压：
tar -xvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz cd cudnn-linux-x86_64-8.9.7.29_cuda12-archive然后把头文件和库文件复制到你的 CUDA 安装目录：
sudo cp include/cudnn*.h /usr/local/cuda/include/ sudo cp -P lib/libcudnn* /usr/local/cuda/lib64/ sudo chmod a+r /usr/local/cuda/include/cudnn*.h如果是指定路径方案，把目标路径换成/opt/cuda/cuda-12.4/include和/opt/cuda/cuda-12.4/lib64。-P参数很关键，它能让 cp 保留符号链接属性，避免把原本的.so软链接复制成一堆普通文件。这一点是我吃了不少亏才注意到的，如果你 copy 后库文件看起来像“失联”了，多半就是符号链接没保留。
最后刷新系统加载缓存：
sudo ldconfig3.3 cuDNN 版本匹配原则
cuDNN 必须和 CUDA 版本线匹配。比如 CUDA 11.x 和 CUDA 12.x 的文件不能混用，否则程序运行时符号找不到、版本校验失败。我的原则是：用哪个 CUDA 版本就找对应关键字为cuda11或cuda12的 cuDNN 包，不跨大版本复制。
另外 cuDNN 版本号里的“对应 CUDA 版本”有时候不是那么直观，下载页面会列出每个安装包支持的 CUDA 版本。多花一分钟确认，比装完再排查高效得多。
3.4 验证阶段一般怎么跑通
复制完验证一下是否生效。先确认动态库里能看到 cuDNN：
ldconfig -p | grep cudnn然后看头文件里的版本宏：
cat /usr/local/cuda/include/cudnn_version.h | grep CUDNN_MAJOR再配合 CUDA 自带的样例做最终验证。在默认路径安装中，样例目录一般在/usr/local/cuda/samples。进入1_Utilities/deviceQuery目录，执行make，运行./deviceQuery，能看到显卡信息并显示 PASS 说明 CUDA 工作正常。
如果你的 CUDA 是自定义路径安装，可能没有自动带样例，那就从官方样例仓库拉一份。验证 cuDNN 是否被程序真正调用，最直接的方式是编译一个调用 cuDNN 接口的小程序，链接时能看到/usr/local/cuda/lib64/libcudnn.so即可。
4. 多 CUDA 环境一键切换：从手动改路径到命令式切换
环境装好了，cuDNN 也拷贝成功，接下来就是重点中的重点：如何在多个 CUDA 环境之间快速切换。
4.1 切换环境到底在切什么
很多新手以为切换 CUDA 环境就是改一下 PATH 就行，其实不够。一个 CUDA 环境要真正“切”过去，至少包含四件事：nvcc编译器路径、运行库libcudart的搜索路径、头文件cuda.h的查找位置、以及CUDA_HOME环境变量。
这些变量不一致，后果就是编译时用 A 版本，运行时加载了 B 版本的库，程序崩都不知道崩在哪。所以切换的本质是让这四件事同时指向同一个版本目录。
4.2 基于 update-alternatives 的方案
如果你采用默认路径布局，即各版本安装在/usr/local/cuda-<版本>，建议用update-alternatives管理/usr/local/cuda软链接。这套机制本来是给系统工具做多版本切换的，用来管理 CUDA 也很顺手。
sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-12.4 124 sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-11.8 118后面两个数字是优先级，越大优先级越高，也可以理解为排序权重。切换时执行：
sudo update-alternatives --set cuda /usr/local/cuda-11.8此时/usr/local/cuda软链接会指向/usr/local/cuda-11.8，而你在环境变量里统一写/usr/local/cuda即可，不用每次改路径。用nvcc -V确认，所见即所切。
4.3 基于环境变量脚本的轻量方案
如果你选择了自定义路径，或者不想为一个软链接引入额外工具，环境变量脚本是我更常用的方案。思路很简单：把切换动作封装成一个 shell 函数，执行后立即生效。
在~/.bashrc末尾加上：
setcuda() { local version="$1" local cuda_root="/opt/cuda/cuda-$version" if [ ! -d "$cuda_root" ]; then echo "未找到 CUDA 版本：$cuda_root" return 1 fi export CUDA_HOME="$cuda_root" export PATH="$cuda_root/bin:$PATH" export LD_LIBRARY_PATH="$cuda_root/lib64:$LD_LIBRARY_PATH" hash -r nvcc -V }重新加载配置后，你只需要执行：
setcuda 11.8 setcuda 12.4当前 shell 立刻切换到对应版本。这里用hash -r是为了清掉 shell 对旧命令路径的缓存，否则nvcc可能还是旧的绝对路径结果。
要注意的是，这种脚本方式只能控制你自己 shell 的环境变量。如果程序是由 systemd 服务启动的，需要在服务单元里单独指定环境变量；如果是图形登录的桌面应用，可能要退出重登。多程序并发各自用不同 CUDA 版本时，脚本方案就没那么适用，那更像容器的活。
4.4 切换后最容易翻车的地方
我遇到最多的问题是“明明切了版本，运行时还是老库”。原因通常是LD_LIBRARY_PATH顺序问题。因为 PATH 和 LD_LIBRARY_PATH 都是前缀式追加，老版本的路径如果还在前面，就会被优先找到。所以无脑export PATH=$PATH:$cuda_root/bin是不对的，必须把新版本路径放在前面。
另外，有些应用在启动时通过ldconfig缓存找库，而不是看 LD_LIBRARY_PATH。因此切换完最好执行一次sudo ldconfig，尤其是你复制过 cuDNN 文件之后。
还有一个坑是 CMake 的问题。find_package(CUDAToolkit)通常会优先读CUDAToolkit_ROOT，如果你在 CMake 里硬编码了路径，shell 环境怎么切都没用。所以要切换生效，CMakeLists 中尽量不要写死 CUDA 路径，交给CUDA_HOME环境变量去影响，或者命令行里显式指定-DCUDAToolkit_ROOT=$CUDA_HOME。
5. 常见问题与排查技巧实录
这部分是实操里最容易踩到的泥潭，我按现象来分类，每个问题附上我自己的排查思路。
5.1 驱动不对引出的诡异症状
最常见也是最迷惑人的现象：nvcc -V显示新版本，但你编译并运行样例时，程序报错说驱动版本不够。这不是 CUDA 没装好，而是驱动版本太低。
CUDA Toolkit 版本和驱动版本是两套阶梯。驱动版本决定运行时支持的上限，工具包版本决定你编译代码时使用的 API 上限。工具包再新，驱动跟不上，程序照样跑不了。遇到这种报错，先查驱动状态工具里的驱动版本，再对照 CUDA 工具包要求的驱动版本，低了就先升驱动。别反复重装 CUDA，那是在错误的方向上使劲。
5.2 输入 nvcc -V 却显示旧版本
原因基本可以锁定为PATH顺序或 shell 命令缓存。先执行which nvcc，看找到的是哪个目录下的nvcc。如果指向的是/usr/bin/nvcc，说明系统里本来就有一个通过包管理器装的旧版 CUDA 工具链，它在你设置的 PATH 里排在更前面。
解决办法：要么卸载系统里旧版 CUDA 相关包，要么在环境变量里把/usr/local/cuda/bin放在更长 PATH 的最前面。还有一种可能就是没有重新加载~/.bashrc或没有重开终端，shell 还在用旧缓存。
5.3 编译期找不到头文件、运行期找不到 so
nvcc: No such file or directory，gcc: error: cuda_runtime.h: No such file or directory，这类问题本质上都是“编译器和链接器不知道去哪找 CUDA 文件”。
编译期找不到头文件，先确认$CUDA_HOME/include路径是否正确，然后看 Makefile 或 CMake 里有没有写死错误路径。运行期找不到.so，则优先看LD_LIBRARY_PATH和/etc/ld.so.conf.d/里是否包含对应lib64目录。建议先跑echo $LD_LIBRARY_PATH，确认当前 shell 真的加载了配置。
5.4 cuDNN 权限和软链接引发的复制失败
复制 cuDNN 时没有用-P，会导致符号链接丢失。表现是ls能看到文件，但程序运行时说找不到库。排查时可以看ls -l /usr/local/cuda/lib64/libcudnn.so的输出，正常应该显示... -> libcudnn.so.8这样的箭头，没有箭头就说明链接关系坏了。
还有一种情况是 sudo 复制后所有文件归 root 所有，普通用户运行时出现 Permission denied。如果目录本身权限没问题，只是文件只读，一般影响不大；但如果库文件没有读权限，需要chmod a+r修正。别用 chmod 777 这种粗暴方式，除非这台机器只有你一个人用。
5.5 快速判断该去哪查资料的心态与思路
遇到问题先不要急着到处搜，把报错原文完整读一遍，然后分三个方向判断：编译期、链接期、运行期。
编译期报错找nvcc和头文件；链接期报错找-L和.so文件；运行期报错找LD_LIBRARY_PATH、ldconfig缓存和驱动版本。确定阶段后，再带着报错关键字去官方安装文档和社区搜，效率会高很多。
下面是这段时间我常用的问题速查表：
| 现象 | 排查命令/思路 | 常见原因 |
|---|---|---|
| nvcc 命令不存在 | which nvcc | PATH 未配置或配置未加载 |
| nvcc 版本是旧的 | ls -l /usr/local/cuda | PATH 顺序、软链接指向旧版 |
| 运行程序报驱动不足 | 查看驱动版本 | 驱动版本低于 CUDA runtime 要求 |
| 编译找不到 cuda_runtime.h | echo $CUDA_HOME | 头文件路径未配置或 CMake 写死 |
| 运行找不到 libcudnn.so | ldconfig -p ｜ grep cudnn | 复制丢失符号链接或未 ldconfig |
| 切换后没效果 | echo $LD_LIBRARY_PATH | 新路径没放在前面，或 shell 缓存 |
6. 实用小技巧与收尾
最后分享几个我在实际使用中觉得非常管用的细节，有的能省时间，有的能救命。
6.1 安装前给现有环境拍一张快照
在多版本环境里折腾，最怕装完发现某个原有软件跑不了了。我现在的习惯是安装前先记录一下当前环境的关键路径和库列表：
ls -l /usr/local/cuda* > cuda_before.txt echo $LD_LIBRARY_PATH > ld_before.txt ldconfig -p | grep cuda > ldconfig_before.txt装完新版本后，一旦发现问题，拿这些文件去对比，很快能定位出是谁被动了。这比靠记忆排查靠谱得多。
6.2 指定路径环境也要留一个稳定软链接
即便你走的是指定路径方案，我也建议单独建一个/usr/local/cuda软链接，手动指向当前“默认”使用的版本：
sudo ln -sfn /opt/cuda/cuda-11.8 /usr/local/cuda原因很简单：有些第三方软件就是死脑筋地看/usr/local/cuda，不看你配置的环境变量。留一个稳定软链接，既能满足这些软件的默认搜索，也不影响你自己通过环境变量切换其他版本。两条路可以共存，不一定非要二选一。
6.3 我最深的一点体会
这个多版本切换方案我用了很久，体会最深的是：环境管理本质上不是技术问题，而是“可回滚性”问题。你需要的不是“当前一切都对”，而是“改错了能快速退回去”。
默认路径给了你最简单的入口，指定路径给了你最灵活的退路，update-alternatives 和脚本切换则把这两者串成了一条可控的工作流。只要目录独立、路径明确、切换命令可复现，无论以后项目要求什么奇奇怪怪的 CUDA 版本组合，你都能比较从容地接住。动手之前多想一步“这台机器会被多少人、多少项目使用”，远比急着复制一条安装命令更有价值。
