企业官网建设流程全解析

1. 先别急着敲命令:把 CUDA、驱动、工具包这三层关系理清楚

我见过太多人在这件事上翻车:一台好好的 Ubuntu 工作站,原本只是想升级个 CUDA 版本,结果装完图形界面进不去,或者nvidia-smi直接报错,最后只能重装系统。问题基本不在操作手法上,而在于对 Ubuntu 下 CUDA 这套东西的层级结构没搞清楚,就跟着某篇教程从头到尾抄了一遍。所以这篇东西我不打算一上来就贴命令,先把结构讲透,后面每一步你才知道自己在干什么、动的是哪一层。

在 Linux 世界里,CUDA 相关的东西其实分成三层,彼此独立又互相制约。最底层是内核态驱动(kernel module),也就是nvidia.ko这类模块,它的版本号就是你nvidia-smi右上角看到的那个 550.xx、535.xx;中间层是用户态的驱动库,主要是libcuda.so,它必须和内核模块版本一致,这也是"Driver/library version mismatch"这个经典报错的来源;最上层才是CUDA Toolkit,包含nvcc编译器、cudart运行时、cuBLAS/cuDNN/cuFFT这些数学库,它们装在/usr/local/cuda-X.Y下面。很多人以为自己"卸载了 CUDA",其实只删了最上层,Toolkit 没了但驱动还在;也有人"卸载了 CUDA"顺手把驱动也带走了,图形界面自然就崩了。

这里要额外提一句,nvidia-smi显示的 "CUDA Version: 12.4" 并不代表你装了 CUDA 12.4,它只是说当前驱动最高支持到 12.4 这个运行时版本。这就是为什么你驱动是 535,却依然能跑用 11.8 编译的程序——CUDA 有向后兼容机制。反过来,驱动太旧就撑不起新 Toolkit,比如 470 系驱动是撑不起 CUDA 12.x 的,装了也白装。理解这一点,你就能判断什么时候需要连驱动一起换,什么时候只需要动 Toolkit。

1.1 deb 方式和 run 方式到底差在哪

这两种方式的区别,本质上是包管理器接管和安装器自己接管的区别。

deb方式指的是把 NVIDIA 的 apt 仓库源加到系统里,然后用apt install装。它的好处是依赖关系由 apt 自动处理,升级、卸载、查询状态都走标准流程,dpkg -l | grep cuda能清清楚楚列出装了哪些包。坏处是 apt 仓库里cuda这个元包会默认勾带驱动,一个不小心就把你原本稳定的驱动升级了,结果 X Server 挂了。

run方式指的是下载一个几百 MB 到几个 GB 的.run可执行文件,手动执行安装。它的好处是选项颗粒度极细,可以只装 Toolkit 不碰驱动,适合需要精确控制版本、或者机器没法连外网的场景。坏处是它绕过了包管理器,卸载要靠自带的cuda-uninstaller,残留文件需要自己清理,而且和 apt 装的驱动容易打架。

1.2 一张表说清楚该怎么选

提示:如果你的机器已经有一份能正常工作的驱动,并且你只是想加一个新版本的 Toolkit,那首选用deb方式装cuda-toolkit-X-Y(注意没有cuda-这个前缀包),或者用run方式并在界面里取消 Driver 勾选。这两条路都能保住你现有的驱动。

搞清楚这些之后,后面的操作就不会是"照抄命令",而是"我知道我在动哪一层"。接下来按流程走:先体检,再卸载,再安装。

2. 卸载之前先做体检:搞清楚机器上到底有什么

卸载这件事,最怕的就是"凭印象操作"。你记得半年前装过 CUDA,但不记得是 deb 还是 run,也不记得装在哪、装了几个版本。这种情况下直接上手删,基本等于赌运气。所以第一步永远是把现状摸清楚,这个动作花五分钟,能省掉后面五小时的排查。

体检要看的维度其实不多:有没有 NVIDIA 卡、驱动是什么版本、装了哪些 CUDA Toolkit、分别在哪里、是 apt 装的还是 run 装的、有没有 cuDNN、环境变量里配了什么。这几项查完,一台机器的"家底"就清楚了。我建议你把体检的命令存成一个脚本,每次动环境前跑一遍,输出留着,出问题时可以对照。

2.1 一套体检命令,把家底摸清楚

# 1. 显卡和驱动状态 nvidia-smi lspci | grep -i nvidia cat /proc/driver/nvidia/version # 2. 已安装的 CUDA Toolkit 目录 ls -l /usr/local/ | grep cuda # 3. 当前 nvcc 指向哪里 which nvcc nvcc -V # 4. apt 装的 CUDA/NVIDIA 相关包 dpkg -l | grep -i cuda dpkg -l | grep -i nvidia apt list --installed 2>/dev/null | grep -i cuda # 5. 环境变量里的 CUDA 配置 echo $PATH | tr ':' '\n' | grep -i cuda echo $LD_LIBRARY_PATH grep -r "cuda" ~/.bashrc /etc/profile /etc/profile.d/ 2>/dev/null # 6. 动态库加载配置 cat /etc/ld.so.conf.d/*cuda* 2>/dev/null

第 4 步的输出特别关键。如果你看到cuda-toolkit-12-4、cuda-12-4、cuda-drivers-550这类包名,说明是deb方式;如果dpkg里干干净净,但/usr/local/下面有cuda-11.8这种目录,并且目录里有bin/uninstall_cuda_11.8.pl或bin/cuda-uninstaller,那就是run方式。两种方式的清理手法完全不同,所以这个判断绝不能省。

2.2 卸载前的三件保命事

第一件是备份环境变量文件。~/.bashrc、/etc/profile.d/下面那些cuda.sh、cuda_path.sh之类的文件,建议先复制到/tmp或者你的 home 目录。卸载完之后你会发现有些残留的 PATH 指向已经不存在的目录,虽然不致命,但每次开终端都提示 command not found,烦人。

第二件是记录当前可用的版本组合。比如记下"驱动 535.171.04 + CUDA 11.8 + cuDNN 8.9.7 + PyTorch 2.2.1 是能跑的",这样万一新装的版本有问题,你能快速回退到这个已知可用的组合。这个记录方式很土,就是写个文本文件扔在 home 目录,但真的好用。

第三件是确认你有没有图形界面依赖。如果你是在这台机器上直接用桌面环境,那卸载驱动这个动作要极其谨慎;如果是通过 SSH 远程操作的无头服务器,那就没这个顾虑。判断方法很简单,echo $DISPLAY,有输出说明当前会话在图形环境里;还可以看systemctl get-default,如果是graphical.target,说明开机进桌面。

注意:卸载 NVIDIA 驱动前,务必确认你不需要图形界面,或者已经准备好了通过 SSH 或 TTY 恢复的手段。一旦驱动被删,graphical.target会起不来,你会掉到黑屏或者低分辨率的 TTY 里。这时候Ctrl+Alt+F2切到 tty2 还能救,但前提是你知道 root 密码。

2.3 如果要连驱动一起卸,先处理 nouveau

Ubuntu 自带一个开源显卡驱动叫nouveau,它和 NVIDIA 闭源驱动是冲突的。通常装了官方驱动之后,安装程序会自动 blacklist 掉 nouveau。但当你要重新装驱动时,得确认 nouveau 确实被禁掉了,否则装完驱动重启,两个驱动抢设备,结果又是黑屏。

检查方法:

lsmod | grep nouveau

有输出就说明 nouveau 还在加载。禁用方式:

sudo bash -c 'cat > /etc/modprobe.d/blacklist-nvidia-nouveau.conf <<EOF blacklist nouveau options nouveau modeset=0 EOF' sudo update-initramfs -u

执行完必须重启,重启后再lsmod | grep nouveau,输出为空才算了事。这一步很多人跳过,然后在装驱动时反复失败,还以为是安装包有问题。

3. deb 方式安装:走 apt 仓库的完整流程

deb方式是我最推荐的日常方案,原因就一个:它把状态管理交给了系统本身。你装了哪些包、什么版本、被谁依赖,dpkg和apt都记得清清楚楚,升级和回滚都有据可查。用run方式装久了,机器上会慢慢积累一堆没人知道来历的文件,过两年接手的人一脸懵。

不过deb方式有个必须绕开的坑,就是包名的选择。NVIDIA 的仓库里有三个名字长得极像的包:

• cuda:元包,会连带驱动一起装,新手最容易被这个坑到
• cuda-toolkit-X-Y:只装 Toolkit(编译器、运行库、数学库),不碰驱动
• cuda-drivers-X-Y/cuda-drivers:只装驱动

大部分"我只想升级 CUDA 版本"的场景,应该装的是第二个。

3.1 仓库配置:keyring 是怎么一回事

早期教程会让你apt-key add加 GPG 密钥,那个做法在新版 Ubuntu 上已经被弃用了,现在官方推荐用cuda-keyring这个 deb 包来管理密钥和源。以 Ubuntu 22.04 为例:

# 下载并安装 keyring 包,它会自动把源和密钥写到正确位置 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt-get update

这里的原理值得说一下:cuda-keyring包做的事,就是把 GPG 公钥放到/usr/share/keyrings/,并在/etc/apt/sources.list.d/cuda-ubuntu2204-x86_64.list里写入仓库地址,同时在源配置里用signed-by=指定用哪个 keyring 文件验签。这样比全局apt-key更安全,因为密钥只对这个源生效,不会影响系统其他仓库。

如果你的系统是 Ubuntu 20.04 或 24.04,把 URL 里的ubuntu2204换成ubuntu2004、ubuntu2404即可。这一步搞错了会出现404 Not Found,很多人以为是网络问题,其实是路径里的系统代号不对。

3.2 安装过程中的关键选择

更新完源之后,先别急着装,先看看有哪些版本可选:

apt-cache search cuda-toolkit | grep -E "cuda-toolkit-[0-9]+-[0-9]+"

假设你要装 12.4:

sudo apt-get install -y cuda-toolkit-12-4

装完之后,/usr/local/下会出现cuda-12.4目录。注意,deb方式不会自动帮你建/usr/local/cuda这个软链接,也不会自动配 PATH,这两件事得自己做。

如果你确实需要连驱动一起装(比如全新机器),那就装cuda-12-4,但装之前一定要确认你接受当前驱动被替换。我个人的习惯是:驱动单独管理,用ubuntu-drivers或者单独的cuda-drivers-X-Y,Toolkit 用cuda-toolkit-X-Y,两层分开升级,出问题的时候影响面小。

关于 gcc 版本,这是deb方式装完最容易踩的第二个坑。CUDA 12.4 支持的最高 gcc 是 13,但某些版本对 gcc 更挑,比如 CUDA 11.8 对 gcc 12 就报unsupported GNU version。Ubuntu 22.04 默认 gcc 11,一般没事;Ubuntu 24.04 默认 gcc 13,装 CUDA 11.x 就会炸。处理方式:

sudo apt-get install -y gcc-12 g++-12 # 然后在 /usr/local/cuda-11.8/bin 下做软链接,让 nvcc 优先找到 gcc-12 sudo ln -sf /usr/bin/gcc-12 /usr/local/cuda-11.8/bin/gcc sudo ln -sf /usr/bin/g++-12 /usr/local/cuda-11.8/bin/g++

做软链接这个技巧比改update-alternatives更安全,因为它只影响 CUDA 编译器的查找路径,不动系统全局的 gcc 默认版本,其他程序不受牵连。

3.3 环境变量:两种写法,各有取舍

配 PATH 和LD_LIBRARY_PATH有两种常见写法,一种写进用户级的~/.bashrc,一种写进系统级的/etc/profile.d/cuda.sh。

~/.bashrc适合只有你自己用的开发机,简单直接。追加内容:

export PATH=/usr/local/cuda-12.4/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda-12.4/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

${PATH:+:${PATH}}这种写法是为了避免 PATH 为空时多出一个冒号,细节但专业。

/etc/profile.d/cuda.sh适合多人共用的服务器,对所有登录用户生效。内容和上面一样,写完给个执行权限:

sudo chmod +x /etc/profile.d/cuda.sh

改完记得source ~/.bashrc或者重开终端,然后用nvcc -V验证。这里有个细节:LD_LIBRARY_PATH平时其实不一定需要,因为deb方式会把库文件路径写进/etc/ld.so.conf.d/,交给ldconfig管理。但很多深度学习框架和第三方软件会去读这个环境变量,所以配上有备无患。真正起作用的还是ldconfig缓存,配完之后跑一次:

sudo ldconfig

3.4 deb 方式的卸载:purge 和 autoremove 的正确姿势

deb方式的卸载相对干净,但模式匹配一定要写对。假设你要清掉所有 CUDA 相关的包:

# 先看一眼会删掉什么,不要直接执行 dpkg -l | grep -i cuda dpkg -l | grep -i nvidia # 删除 CUDA 相关包,保留驱动 sudo apt-get --purge remove "*cuda-toolkit*" "*cublas*" "*cufft*" "*curand*" "*cusolver*" "*cusparse*" "*npp*" "*nvjpeg*" "nsight*" # 如果确认要连驱动一起删 sudo apt-get --purge remove "*nvidia*" "libxnvctrl*" # 清理孤立依赖 sudo apt-get autoremove --purge sudo apt-get autoclean

--purge和普通remove的区别在于,前者会把配置文件一起删掉,后者只删程序保留配置。CUDA 这种要彻底清干净的场景,必须用--purge。autoremove则是把那些因为 CUDA 被装上、现在没人依赖的库一并清走,能省不少空间。

删完之后还要检查两处残留:一是/usr/local/下面是否还有cuda*目录,deb方式卸载通常不留,但升级过程中可能留下空目录;二是/etc/ld.so.conf.d/里是否还有指向已删除路径的.conf文件,有的话删掉再sudo ldconfig,否则会报cannot open shared object file。

4. run 方式安装:离线安装包的完整流程

需要run方式的场景其实挺明确:机器不能连外网、需要精确控制驱动版本、或者想在同一台机器上装多个彼此差异很大的 Toolkit 版本。我待过的一个实验室集群就是这样,计算节点全在内网,只能把.run文件拷进去手动装。

run方式的整个流程可以拆成下载校验、安装选项、环境配置、卸载四个环节,其中下载校验环节藏着最经典的一个坑,就是那个gzip: stdin: invalid compressed>wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run # 对比官方页面给出的 md5 md5sum cuda_12.4.0_550.54.14_linux.run

现在说那个 gzip 报错。这个错误的字面意思是"输入的压缩数据格式非法",它出现在.run文件执行过程中——因为.run其实是一个自解压脚本,前半部分是 shell,后半部分是 gzip 压缩的 payload。当 shell 部分跑到解压那一步,如果 payload 损坏或者不完整,就报这个错。

原因基本就三种:一是网络中断导致下载不完整,文件大小比官方标注的小;二是用wget -c续传时,服务端不支持 Range 或者中途返回了 HTML 错误页,续传把垃圾数据拼了上去;三是用浏览器下载时被某些安全软件截断或修改。我遇到过最离谱的一次,是同事用某下载工具"加速"下载,结果文件头被塞了额外的字节,md5sum对不上,执行就报这个错。

处理办法很粗暴:删掉重下,不要用续传。如果网络确实不稳,先看官方给的 sha256 或 md5,下完立刻校验,对了再执行。还有一种情况是磁盘空间不足导致写入截断,顺手df -h看一眼也不亏。另外,某些终端环境会把下载到的内容当成文本处理,虽然少见,但如果文件大小明显不对而 md5 又对上,那就要怀疑下载链路被中间环节动过了。

4.2 安装选项逐条拆解

执行.run文件:

sudo sh cuda_12.4.0_550.54.14_linux.run

启动后会先过一个协议页面,输入accept继续。接下来是组件选择界面,通常有这几项:

• Driver:驱动。已有可用驱动的话,务必把这一项的勾去掉,否则它会用自带驱动覆盖你现有的。
• CUDA Toolkit 12.4:核心,必选。装完之后问你要Toolkit Location,默认/usr/local/cuda-12.4,建议保持默认。
• CUDA Samples 12.4:示例代码。早期版本用来跑deviceQuery验证,现在建议装,占空间不大,而且能顺手确认安装是否成功。
• CUDA Demo Suite / Documentation:一般用不上,不装。

如果你要无人值守安装(比如写进自动化脚本),可以用命令行参数直接指定:

sudo sh cuda_12.4.0_550.54.14_linux.run \ --silent \ --toolkit \ --toolkitpath=/usr/local/cuda-12.4 \ --samples \ --samplespath=/usr/local/cuda-12.4/samples \ --no-opengl-libs

--no-opengl-libs这个参数值得单独说。它表示不安装 OpenGL 相关的库。在装了桌面环境的机器上,不加这个参数的话,安装程序可能覆盖系统的libGL.so,导致图形界面出现渲染异常甚至进不去。无头服务器上加不加都行,但养成加上的习惯没坏处。

注意:--silent模式下如果检测到已有驱动版本高于待装驱动,它可能直接跳过驱动安装,也可能报错退出,行为在不同版本间有差异。生产环境用静默安装前,建议先在测试机跑一遍,把日志留下来。

4.3 run 方式的卸载:uninstaller 加手动收尾

run方式的卸载入口在安装目录里。分版本:

# CUDA 11.x 及更早 sudo /usr/local/cuda-11.8/bin/uninstall_cuda_11.8.pl # CUDA 11.4 之后统一为 sudo /usr/local/cuda-12.4/bin/cuda-uninstaller sudo rm -rf /usr/local/cuda-12.4

uninstall_cuda_X.Y.pl是 Perl 脚本,新版本改成了编译后的cuda-uninstaller,功能一样,都是按安装时记录的清单去删文件。但要注意,它只删它自己装的东西,你在安装之后手动拷进去的 cuDNN 文件、自己编译的 samples、改过的配置文件,它一概不管。所以卸载完必须手动检查:

# 看软链接是不是还指着已删目录 ls -l /usr/local/cuda # 看环境变量文件是否还残留 grep -rn "cuda-12.4" ~/.bashrc /etc/profile.d/ 2>/dev/null # 看动态库缓存里是否还有失效路径 cat /etc/ld.so.conf.d/*cuda* 2>/dev/null sudo ldconfig

如果卸载的是通过run方式装的驱动,那用的是另一个入口:

sudo /usr/bin/nvidia-uninstall

这个命令会清掉驱动相关的内核模块和用户态库。执行完之后必须重启,否则当前内核里还加载着旧模块,状态会很乱。

5. 多版本共存与切换:一套能长期用的管理方案

真实项目里,一台机器同时存在两个甚至三个 CUDA 版本是常态。老项目锁死在 11.3,新框架又要 12.1,你不可能每次都卸载重装。好在这件事在 Linux 上并不难,核心思路就是每个版本装在自己的独立目录里,用一个软链接指向"当前默认版本"。

5.1 用软链接做默认版本切换

假设你已经有/usr/local/cuda-11.8和/usr/local/cuda-12.4,并且环境变量里配的是/usr/local/cuda(不带版本号)。那切换就只需要改软链接:

# 切到 11.8 sudo rm -rf /usr/local/cuda sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda # 切到 12.4 sudo rm -rf /usr/local/cuda sudo ln -s /usr/local/cuda-12.4 /usr/local/cuda

配合~/.bashrc里的写法:

export PATH=/usr/local/cuda/bin${PATH:+:${PATH}} export LD_LIBRARY_PATH=/usr/local/cuda/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}

这样改软链接就改了整个工具链的指向,重开终端nvcc -V就能看到对应版本。缺点是rm -rf那一下有点吓人,建议包成一个小函数写进.bashrc:

cuda-switch() { if [ -d "/usr/local/cuda-$1" ]; then sudo rm -rf /usr/local/cuda sudo ln -s /usr/local/cuda-$1 /usr/local/cuda echo "Switched to CUDA $1" nvcc -V | grep release else echo "CUDA $1 not found in /usr/local/" fi }

以后cuda-switch 11.8就切过去了,比手敲两条命令稳当。

5.2 update-alternatives 这个更正规的选择

如果嫌软链接方案土,可以用系统自带的update-alternatives来管理:

sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-11.8 100 sudo update-alternatives --install /usr/local/cuda cuda /usr/local/cuda-12.4 120 sudo update-alternatives --config cuda

最后一条命令会列出所有候选版本让你选,数字大的优先级高。这个方案的好处是切换有记录、有回显,适合多人共用的机器。需要注意的是,update-alternatives管理的本质也是软链接,只是多了一层元数据,所以它和手动ln -s不能混用,否则--config会报状态不一致。

5.3 cuDNN 和 conda 的 CUDA 到底怎么摆

cuDNN 的安装方式跟 CUDA 类似,也有deb和tar两条路。tar方式最直接:

tar -xvf cudnn-linux-x86_64-8.9.7.29_cuda12-archive.tar.xz sudo cp cudnn-*-archive/include/cudnn*.h /usr/local/cuda-12.4/include/ sudo cp -P cudnn-*-archive/lib/libcudnn* /usr/local/cuda-12.4/lib64/ sudo chmod a+r /usr/local/cuda-12.4/include/cudnn*.h /usr/local/cuda-12.4/lib64/libcudnn*

拷完之后sudo ldconfig。cuDNN 的版本必须和 CUDA 主版本对应,拿cuda11的包去配 CUDA 12,编译时不一定报错,跑起来才崩,排查起来很痛苦。

然后是 conda。很多人装了conda install cudatoolkit=11.8之后,以为系统里就有 CUDA 11.8 了,结果nvcc -V找不到命令。原因很简单:conda装的 CUDA 是放在虚拟环境目录里的运行时库,不含编译器,它存在的意义是给 PyTorch 这类框架用,不和系统 Toolkit 抢位置。判断方法:

python -c "import torch; print(torch.version.cuda, torch.cuda.is_available())"

如果torch.version.cuda显示 11.8,而系统nvcc是 12.4,这是完全正常的组合。要点只有一个:驱动版本必须高于所有用到的运行时版本。驱动 535 可以同时带 11.8 和 12.x 的运行时,反过来就不行。

提示:排查深度学习环境问题时,先跑nvidia-smi确认驱动和最高支持版本,再跑nvcc -V看编译期版本,最后跑torch.version.cuda看运行时版本。这三个数字排在一起,问题基本就定位了。

6. 常见问题与排查速查表

前面讲的是"怎么正确地做",这一节讲"做错了怎么办"。我把这些年实际遇到过的问题按类别整理了一下,附上判断依据和处理办法。这些内容大多不会写在官方文档里,但真出问题的时候,它们比文档管用。

6.1 安装阶段的典型故障

装完之后nvcc找不到。八成是 PATH 没生效。先确认which nvcc有没有输出,没有就echo $PATH看/usr/local/cuda/bin在不在里面。不在的话检查~/.bashrc是否改了、有没有source、当前终端是不是改之前就开着的。最直接的验证方式是开一个新终端再试。

编译时报unsupported GNU version! gcc versions later than 12 are not supported。这是 gcc 版本过高。处理方式在 3.2 节讲过,装一个低版本 gcc 并在 CUDA 的bin目录下做软链接。别去动系统默认 gcc,那个影响面太大。

run文件执行报gzip: stdin: invalid compressed>sudo dpkg --configure -a sudo apt-get -f install

这两条会让 apt 把中断的配置补齐、把缺失的依赖补上。通常跑完就恢复正常了。

卸载完nvidia-smi还在,但是报错。说明驱动没删干净,内核模块还在内存里。彻底的做法是先sudo /usr/bin/nvidia-uninstall(run 装的)或apt purge(deb 装的),然后重启,让内核重新加载模块表。重启后如果lsmod | grep nvidia还有输出,检查黑名单文件并重建 initramfs。

/usr/local/cuda软链接变成了红色或者指向不存在的目录。指向的目标被删了。直接sudo rm -rf /usr/local/cuda然后重建正确的软链接,或者干脆不建,直接用带版本号的路径。

卸载完重启,进不了图形界面,停在 TTY。驱动被删了但系统默认还是graphical.target。在 TTY 里登录后,要么装回驱动,要么临时把默认目标改成多用户模式:sudo systemctl set-default multi-user.target。另外检查/etc/X11/xorg.conf,如果里面写死了 NVIDIA 的配置,在驱动被删后会导致 X 启动失败,把它删掉或改名。

6.3 验证与运行阶段的问题

nvidia-smi报Driver/library version mismatch。内核模块和你用户态库版本对不上。最常见的原因是驱动被热升级了但机器没重启。sudo reboot重启基本就好了。如果重启还不行,说明装的驱动包版本本身就是混的,需要统一重装。

torch.cuda.is_available()返回 False。按顺序查三件事:一,nvidia-smi是否正常,不正常就是驱动问题;二,pip show torch看装的是不是+cpu版本的包,CPU 版的 torch 永远不会返回 True;三,torch.version.cuda对应的运行时版本是否高于驱动支持的最高版本,高过就会返回 False。第三条最隐蔽,表现形式就是"驱动明明没问题但就是不能用"。

跑程序报libcudart.so.11.0: cannot open shared object file。运行时找不到库。先确认/usr/local/cuda-11.8/lib64在LD_LIBRARY_PATH里或者被ldconfig收录了。临时验证可以export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH再跑一次,能跑就说明是路径配置问题,去改配置文件。

6.4 一张问题速查表

最后再分享一个我自己用了很久的小习惯:每次动 CUDA 环境之前,把nvidia-smi、nvcc -V、dpkg -l | grep -i cuda、ls -l /usr/local/ | grep cuda这四条命令的输出重定向到一个带日期的文件里,比如~/env-backup/20240612-before.txt,改完之后再存一份-after.txt。看着有点笨,但真出问题时,对比两份记录能立刻定位到是哪一步引入了变化。我靠这个习惯救回过不止一台机器,也帮同事省下过好几次重装系统的时间。环境管理这事,很多时候拼的不是技术深度,而是有没有留下可回溯的痕迹。