装 CUDA 这种活，说难是真不难，但网上的教程大多只给命令不给思路，照着敲完，重启一下发现要么驱动挂了，要么 nvcc 版本对不上。尤其是“Ubuntu 20 Desktop 装 CUDA 11.8”这套组合，我前后在各种机器上折腾过太多次了，踩过的坑包括黑屏、登录循环、gcc 版本不兼容、Secure Boot 拦截驱动加载等等。这次干脆把从零到能跑通的完整流程，连同每个关键步骤背后的原因一起写出来，希望你能一次搞定。
先说清楚这个标题背后对应的真实场景：一台运行 Ubuntu 20.04 桌面版的机器，装 CUDA 11.8，核心目标就三个——显卡驱动能被系统正确识别、nvidia-smi 能正常输出、nvcc 编译工具链能编译并运行 CUDA 程序。绝大多数人装它是为了跑深度学习框架，比如 PyTorch 2.0 的官方预编译包就是基于 CUDA 11.8 构建的；也有做图像处理、CUDA 课程作业、ROS+GPU 加速的同学。这类需求有个共同点：驱动必须先行，CUDA Toolkit 是第二步，顺序反了必出问题。
如果你是第一次在桌面上装 CUDA，建议把这篇文章从头到尾读一遍再动手。文中的命令我都在 Ubuntu 20.04 桌面版上实测过，所有注意事项和坑位也都标出来了，照着做就行。
1. 动手前先想明白：版本匹配与装机思路
1.1 为什么是 CUDA 11.8 而不是最新版本
你可能会有疑问：现在 CUDA 都出 12.x 了，为什么还要装 11.8？答案很简单：生态兼容性。CUDA 版本不是越新越好，关键是看你要用的框架对它的支持程度。
PyTorch 官方编译的稳定版（比如 2.0.1）在 Linux 上提供了 cu118 和 cu121 两套 wheel 包，但 cu118 版本覆盖的模型库、第三方扩展最全。很多开源项目在 README 里明确写“要求 CUDA 11.8”，因为作者本身就是在该版本下测试的。另一个原因是驱动兼容范围：CUDA 11.8 对应驱动分支是 R520，也就是说 520.61.05 及以上的驱动都能支持它，这个门槛比 CUDA 12（需要 525 以上）低不少，对一些旧卡、旧笔记本特别友好。
注意区分两个概念：驱动版本决定 GPU 能不能干活，CUDA Toolkit 版本决定你能用哪个版本的编译器和运行时。驱动往下兼容旧的 CUDA Toolkit，但不向上兼容——比如你的驱动只有 520，却想跑 CUDA 12.x 的代码，那是不可能的。
这里列一个简单的对照表：
| 组件 | 最低要求 | 我推荐的版本 |
|---|---|---|
| NVIDIA 驱动 | 520.61.05 及以上 | 520 或 530 系列稳定版 |
| CUDA Toolkit | 11.8.0 | 11.8.0（带补丁则装 update 版） |
| GCC 编译器 | 官方支持到 GCC 11 | Ubuntu 20.04 自带的 GCC 9 完全没问题 |
1.2 装机前的系统体检清单
在下载任何东西之前，先花五分钟确认机器状态，这一步能省掉后续大量排查时间。
- 检查 GPU 型号：
lspci | grep -i nvidia。如果没有任何输出，先确认显卡是不是真的插好、BIOS 里有没有禁用独显。 - 检查内核版本：
uname -r。任何驱动安装都需要与当前内核匹配的头文件，提前装好：sudo apt install linux-headers-$(uname -r) build-essential dkms。 - 检查是否已经装过 NVIDIA 驱动：
nvidia-smi如果报错，说明当前没驱动或驱动没加载；如果之前装过但想重装，先彻底卸载（第 5 章会讲）。 - 检查 nouveau 开源驱动是否被加载：
lsmod | grep nouveau。有输出就说明还在用开源驱动，安装闭源驱动前必须屏蔽它。 - 检查磁盘空间：
df -h /usr/local。CUDA Toolkit 解压完大概要 3.5GB 空闲，不够就先清理。 - 检查 Secure Boot 状态：
mokutil --sb-state。如果显示 enabled，装驱动会遇到签名验证问题，后面单独说。
这些检查做完，机器是什么状态你心里就有数了。接下来进入正题。
2. 显卡驱动：在装 CUDA 之前，驱动必须先行
2.1 三种安装驱动的方式，我为什么推荐 apt 仓库
Ubuntu 桌面上装 NVIDIA 驱动基本上有三条路：图形界面的“软件和更新”里的附加驱动页签、命令行 apt 安装、NVIDIA 官方跑 runfile。三条路各有优劣，我的建议非常明确：桌面版优先用 apt。
对比一下你就明白了：
| 方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| GUI 附加驱动 | 点几下鼠标就行 | 版本可选范围有限 | 不想敲命令的新手 |
| apt 安装 | 自动处理模块编译、内核升级后自动重建 | 版本略旧 | 桌面环境首选，稳定 |
| 官方 runfile | 版本最新、参数可控 | 容易和 X 图形栈冲突，卸载麻烦 | 需要特定新驱动版本时才用 |
apt 方式最大的好处是跟系统深度集成：内核更新后，DKMS 会自动重新编译驱动模块，你不需要管；卸载也是apt purge干干净净。runfile 在桌面上有个著名的坑——它会覆盖系统的 OpenGL 相关库文件，装完大概率陷入“登录循环”，这个我后面会详细讲。
2.2 从零到 nvidia-smi 能跑通的完整流程
第一步，屏蔽 nouveau。Ubuntu 20.04 默认可能加载开源驱动 nouveau，它和 NVIDIA 官方驱动直接冲突。创建一个屏蔽配置文件：
sudo bash -c 'echo "blacklist nouveau" >> /etc/modprobe.d/blacklist-nouveau.conf' sudo bash -c 'echo "options nouveau modeset=0" >> /etc/modprobe.d/blacklist-nouveau.conf'然后更新内核镜像并重启：
sudo update-initramfs -u sudo reboot重启后确认 nouveau 确实不再加载：lsmod | grep nouveau，没有输出就对了。如果有，检查文件是否写对，或者 BIOS 里是否强制开启了什么独显模式。
第二步，通过 apt 安装驱动。我建议用 520 或 530 系列的驱动包，它们对 CUDA 11.8 支持得很稳：
sudo apt update sudo apt install nvidia-driver-520这里有个细节：Ubuntu 20.04 默认的 apt 源里驱动包版本可能不够新，如果找不到 nvidia-driver-520，可以先把显卡驱动 PPA 加上再试：
sudo add-apt-repository ppa:graphics-drivers sudo apt update sudo apt install nvidia-driver-520第三步，重启并验证。装完驱动必须重启，让内核加载 nvidia 模块。重启后终端里敲：
nvidia-smi正常会显示 GPU 型号、驱动版本、显存占用等信息。看到这个画面，说明驱动层已经通了，可以进入下一步装 CUDA Toolkit。如果这里就报错，先别往下走，去第 5 章把驱动问题解决再说。
注意：如果你坚持要用 runfile 方式装驱动，桌面上必须在纯文本终端里操作（Ctrl+Alt+F3 进入 tty），并确保图形界面是停止状态（
sudo systemctl isolate multi-user.target）。安装命令务必加上--no-opengl-files，这是避免登录循环的关键。即便如此，我依然强烈建议桌面用户用 apt。
3. 安装 CUDA 11.8 Toolkit：runfile 方案全解析
3.1 下载安装包与校验完整性
驱动通了之后，CUDA Toolkit 只装工具链本身就行，不要再装驱动。这是最容易翻车的地方——很多人用 CUDA 的 runfile 一条龙装驱动+Toolkit，结果覆盖了刚才 apt 装好的驱动，版本还不一定匹配，直接把系统搞乱。
下载 CUDA 11.8.0 的 runfile 安装包：
cd ~/Downloads wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run下载完建议校验一下文件完整性，官网会提供 sha256 校验值，比对方法：
sha256sum cuda_11.8.0_520.61.05_linux.run看到的结果和官网页面给出的校验值一致再继续。这一步不是为了防黑客，而是防止下载过程中文件损坏——装到一半报“无法解压”再回头排查，浪费时间。
3.2 安装命令的细节和参数说明
执行安装：
sudo sh cuda_11.8.0_520.61.05_linux.run这里会走进一个文本交互界面，用方向键和回车操作。第一次运行它会问你接不接受条款，输入 accept 回车。然后进入组件选择界面，重点来了：
- Driver：这一项必须取消勾选。因为我们前面已经用 apt 装好驱动了，再装一份会出乱子。
- CUDA Toolkit 11.8：勾选，这是核心。
- CUDA Samples 11.8：建议勾选，后面验证环境要用官方的 deviceQuery 示例。
- CUDA Documentation：随意，文档占用空间不小，不需要可以去掉。
如果你不想进交互界面，可以用命令行参数实现静默安装，同样只装 Toolkit 和 Samples：
sudo sh cuda_11.8.0_520.61.05_linux.run --toolkit --samples --silent这两个参数的含义很直白，--toolkit装开发工具链，--samples装示例代码。为什么要传--silent？因为非交互模式下安装器会按默认行为执行，减少人为误操作。
装完之后，目录结构是这样的：
/usr/local/cuda-11.8：实际的版本目录/usr/local/cuda：一个符号链接，指向当前默认版本
这个软链接设计得非常聪明：你以后装了 CUDA 12.x，只要把软链接指向 12 的目录，所有依赖/usr/local/cuda的环境变量路径都不用改。现在不用纠结，保持默认即可。
3.3 配置环境变量并验证 nvcc
CUDA 装完不会自动把命令加入 PATH，系统根本不知道上哪找 nvcc。这是新手最容易困惑的环节。需要把两个路径告诉系统：
echo 'export PATH=/usr/local/cuda-11.8/bin${PATH:+:${PATH}}' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}' >> ~/.bashrc source ~/.bashrcPATH 负责找到 nvcc 可执行文件；LD_LIBRARY_PATH 负责找到 CUDA 的运行时库（libcudart.so 等）。缺了后者，编译能过，运行时会报找不到共享库。
验证安装：
nvcc -V看到类似下面的输出就说明 Toolkit 装好了：
nvcc: NVIDIA (R) Cuda compiler driver Copyright (c) 2005-2022 NVIDIA Corporation Built on ... Cuda compilation tools, release 11.8, V11.8.89这里有个常见误区要澄清：nvcc -V显示的版本是 Toolkit 版本，nvidia-smi右上角显示的“CUDA Version: 11.8”是驱动支持的 CUDA 运行时版本，两者含义不同，数值接近但不是一回事。判断系统能不能用，以 nvcc 为准。
4. 验证环境是否真的能干活：从命令到实际编译
4.1 两种命令验证与状态判断
装完只有一种验证方式是不保险的。我的习惯是同时看两个命令：
nvidia-smi：确认 GPU 驱动端正常，显存能读到。nvcc -V：确认编译工具链就位。
如果 nvidia-smi 正常但 nvcc 报 command not found，说明环境变量没生效，回头检查 .bashrc；如果 nvcc 正常但 nvidia-smi 报“couldn't communicate with the NVIDIA driver”，说明驱动挂了，排查第 5 章的内容。
4.2 用官方示例编译检测，比啥都靠谱
命令能跑通不等于真的能编译、能调用 GPU。最稳的验证方式是编译官方的 deviceQuery 示例：
cd /usr/local/cuda/samples/1_Utilities/deviceQuery sudo make ./deviceQuery如果一切正常，结尾会输出一串显卡信息，并且最后一行是：
Result = PASS看到 PASS 就可以放心了，这把你的驱动、Toolkit、运行时全链路都验证了一遍。顺便还可以跑一下带宽测试：
cd ../bandwidthTest sudo make ./bandwidthTest这个程序测试显存读写带宽，能跑通说明 CUDA 运行时库加载没问题，后面跑深度学习模型也不会出幺蛾子。
最后拿你真正的场景验证一下：如果你是为了机器学习装 CUDA，装完 PyTorch 后跑一行：
python -c "import torch; print(torch.version.cuda); print(torch.cuda.is_available())"返回11.8和True，整个链路彻底闭环了。
5. 常见问题与排查技巧实录
5.1 重启后 nvidia-smi 报错：驱动模块没加载
这是最经典的问题，报错信息一般是“NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver”。
排查思路按顺序来：第一步lsmod | grep nvidia，看内核模块在不在。如果不在，多半是模块编译失败或者被 block。查看内核日志定位：
sudo dmesg | grep -i nvidia常见的两个原因：一是内核升级后 DKMS 没有自动重建模块（这时候重新执行sudo dkms install -m nvidia -v 520.xx.xx解决）；二是启动时 nouveau 又抢占了（确认 2.2 里屏蔽文件还在）。还有一个别忽略：modprobe nvidia手动加载一次，能加载说明模块本身没问题，纯粹是启动顺序问题，考虑在 GRUB 里加nomodeset参数。
5.2 装完驱动陷入登录循环或者黑屏
桌面版独有的坑，99% 是因为用 runfile 装驱动时覆盖了 OpenGL 库。GDM 启动时需要 OpenGL 渲染，库被替换后图形界面反复重启，看起来就是“输入密码后又回到登录界面”的循环。
我已经说了很多次，桌面环境别用 runfile 装驱动、要用 apt，就是为了避开这个坑。如果已经踩了，补救方法是：Ctrl+Alt+F3 进入 tty，用apt purge nvidia-*把 runfile 装的驱动清掉，然后重新用 apt 安装。如果只是 xorg.conf 被改动导致的，检查/etc/X11/xorg.conf里有没有奇怪的配置，删除重启即可。
5.3 编译示例时提示 GCC 版本不支持
CUDA 11.8 官方支持到 GCC 11，如果你系统升级过编译器到 GCC 12 以上，编译 deviceQuery 会直接报“unsupported GNU version”开头的错误。
两种解决办法：一是装回老版本编译器并切换默认：
sudo apt install gcc-9 g++-9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 60 sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-9 60二是编译时通过环境变量指定主机编译器：
export CUDAHOSTCXX=/usr/bin/g++-9我个人更推荐第二种，因为它只影响当前会话，不会改动系统默认编译器，其他项目不受影响。
5.4 卸载与重装：怎么把系统恢复到干净状态
装坏了要重来，别慌，卸载比安装简单。如果驱动是通过 apt 装的：
sudo apt purge 'nvidia-*' sudo apt --purge autoremoveCUDA Toolkit 通过 runfile 装的，有自带的卸载器：
sudo /usr/local/cuda-11.8/bin/cuda-uninstaller然后再手动清理残余目录：
sudo rm -rf /usr/local/cuda-11.8 /usr/local/cuda最后把 .bashrc 里添加的那两行 export 删除，source 一下，系统就回到干净状态了。这样做的好处是重装时不会受残留文件干扰，特别是软链接残留会导致“nvcc -V 报错但目录存在”这种诡异现象。
6. 写在最后的经验之谈
这活干了这么多次，我的习惯从来都是两步走：先用 apt 装驱动，再用 CUDA runfile 单独装 Toolkit 和 Samples。拆开装的好处是出了问题能在一分钟内定位是驱动层还是工具链层，不会两者互相甩锅。
最后分享一个小技巧：如果你经常要用 sudo 运行 CUDA 相关脚本，会发现普通用户环境变量对 sudo 不生效，导致sudo nvcc时报 command not found。解决办法是把环境变量写进系统级的/etc/profile.d/cuda.sh文件：
sudo bash -c 'echo "export PATH=/usr/local/cuda-11.8/bin:$PATH" > /etc/profile.d/cuda.sh' sudo bash -c 'echo "export LD_LIBRARY_PATH=/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH" >> /etc/profile.d/cuda.sh'这样不仅对所有用户生效，sudo 环境下也能直接找到 nvcc 和 CUDA 库文件。装完一套环境，顺手把这个文件写进去，能省掉后面很多“明明装了为什么找不到”的烦恼。
