Ubuntu 20.04桌面版CUDA 11.8安装避坑全指南

最近帮一位朋友处理他 Ubuntu 20.04 桌面系统上的深度学习环境，他提前在官方下载页拿了 CUDA 11.8 的 runfile，照着 README 一条命令装完，心里还挺踏实。结果第二天开机，登录界面输对密码就黑屏，循环几次直接进不去系统。折腾下来我才发现，问题根本不在 CUDA 安装器本身，而是桌面版 Ubuntu 在显卡驱动、显示管理器和内核模块之间的配合逻辑，比服务器版麻烦得多。

这篇文章把整个「Ubuntu 20 桌面安装 CUDA 11.8」的过程拆开讲，包括装之前要确认的系统状态、旧驱动怎么清干净、桌面版特有的灰屏/循环登录坑、runfile 参数选择、环境变量配置，还有最后怎么用官方样例验证整条链路真的通了。适合刚接触 Linux 深度学习开发、或者已经在 Ubuntu 桌面版上装过驱动但总是翻车的读者，跟着走一遍能少走很多弯路。

1. 安装前先搞清楚：你的桌面系统处于哪种状态

很多人一上来就找 CUDA 下载链接，拿到 runfile 直接开跑，根本不看当前系统里有没有旧驱动、是不是开源驱动在工作、内核和 gcc 版本对不对。这些信息直接决定你后面会不会黑屏、能不能编译样例。

1.1 先看显卡型号和当前驱动是谁在干活

打开终端，先确认显卡型号：

lspci | grep -i nvidia

能看到类似NVIDIA Corporation GA102 [GeForce RTX 3080]的输出就说明显卡被系统识别了。如果没输出，先别急着装 CUDA，可能是显卡没插好、供电不足，或者 BIOS 里没启用独立显卡。

接着看当前实际加载的显卡驱动模块：

lsmod | grep -i nvidia lsmod | grep -i nouveau

正常情况下二选一：要么输出一堆 nvidia 模块，要么输出一堆 nouveau 模块。如果两者都有输出，说明系统已经很乱了，先按本文第 2 部分彻底清理再往下走。如果两者都没有输出，那就是「裸奔」状态，常见于刚装完系统还没装过任何显卡驱动。

还要看一眼有没有装过 CUDA 相关的残留：

nvcc --version

如果你看到command not found，不代表没装过 CUDA，可能是环境变量没配；如果看到了版本号，也要搞清楚这个版本是怎么装的，后面卸载才能干净。

1.2 CUDA 11.8 对 Ubuntu 20.04 的适配：内核与 gcc 别忽视

CUDA 11.8 发布时对应的 Ubuntu 20.04 长期支持版本，官方支持的内核范围很宽，默认的 5.4 和后来的 5.15 HWE 内核都能用。但有一个前提：你系统里的 gcc 版本要能跟 nvcc 配合编译宿主机代码。Ubuntu 20.04 默认带的是 gcc 9.3，工作得很好。如果你之前因为别的项目改过默认 gcc 版本，安装前最好先确认下：

gcc --version uname -r

如果 gcc 版本被改得很新或者挂掉了，后面编译 CUDA samples 时会报一堆莫名其妙的错误。可以先把基础工具链装好：

sudo apt update sudo apt install build-essential linux-headers-$(uname -r)

这条命令同时安装了编译器和当前内核对应的头文件，内核头文件非常重要，驱动编译时会用到。缺了它，很多显卡驱动会编译失败或者装完加载不了。

1.3 一个关键决定：驱动走 apt，还是让 runfile 一起装？

这是整篇文章里最值得先想清楚的问题。CUDA 11.8 的 runfile 安装器里其实捆绑了一个显卡驱动（版本 520.61.05），你可以让它顺便把驱动也装掉，也可以只用它装 CUDA Toolkit，驱动单独用 apt 装。

我强烈建议：驱动走 apt，CUDA Toolkit 走 runfile。

原因有两点。第一，apt 装的驱动会注册到 dkms（Dynamic Kernel Module Support），Linux 内核一旦升级，它会自动重新编译显卡驱动模块，驱动不会丢。而 runfile 附带装的驱动没有这个机制，内核一升级驱动就失效，重启后大概率黑屏或者掉驱动。第二，apt 管理的驱动卸载干净，一条apt purge就能清完；runfile 装的驱动出问题，排查逻辑更像「手工安装的软件」，清理起来要多注意几个路径。

当然如果你的系统里还没法用 apt 装到满足 CUDA 11.8 最低要求的驱动版本（不低于 520），也可以选择让 runfile 装驱动。但从长期维护的角度看，apt 方案省心很多。后面我会按「apt 装驱动 + runfile 只装 Toolkit」这条路展开。

2. 先把旧驱动清干净：避免安装过程直接撞车

CUDA 安装器对系统环境非常「挑剔」，它检测到现有驱动跟它要装的东西不是一套来源，就会报冲突，甚至直接拒绝安装。你如果是从旧版本升级上来的，或者之前用过某款加速计算软件，这一步不能跳。

2.1 怎么判断当前驱动是 apt 装的还是 runfile 装的

判断驱动来源最简单的办法是看软件包管理器的记录：

dpkg -l | grep -i nvidia

如果输出了一堆ii nvidia-driver-xxx、ii libnvidia-xxx之类的条目，说明驱动是 apt 方式装的。如果 dpkg 查不到 nvidia 条目，但nvidia-smi又确实能用，那多半是 runfile 或者 script 方式手动安装的，也可以检查这两个痕迹：

ls /usr/bin/nvidia-uninstall ls /var/lib/nvidia-installer

nvidia-uninstall是 runfile 安装驱动时自动生成的卸载工具，/var/lib/nvidia-installer目录是安装过程的记录。这两个出现任何一个，都说明你用的是 runfile 装的驱动。

2.2 两种卸载路径的具体命令

如果是 apt 派，直接把所有 nvidia 相关包清理掉：

sudo apt purge '*nvidia*' sudo apt autoremove

注意purge '*nvidia*'两边的星号，它匹配所有包含 nvidia 的包。执行完再查一次dpkg -l | grep -i nvidia，确保没剩。如果之前还手动添加过官方 CUDA 的 apt 源（有些教程喜欢用 deb 方式装），还需要清掉源文件：

ls /etc/apt/sources.list.d/ | grep -i cuda

找到 cuda 相关的.list删除，然后sudo apt update。

如果是 runfile 派，先跑自带卸载：

sudo /usr/bin/nvidia-uninstall

过程中会问你是不是真的要卸，后面可能还会问要不要改回 X 配置，建议先选「No」或者保持默认，别让它自动改 X server 配置，避免多改出问题。卸完之后再手动删这些：

sudo rm -rf /usr/local/cuda sudo rm -rf /usr/local/cuda-11.8 sudo rm -rf /var/lib/nvidia-installer

清理完以后最好重启一次，让内核真正卸载掉旧的 nvidia 模块。这一步很多人忽略，直接装的话，新驱动模块可能加载不上，报错信息又指向不明。

2.3 卸不干净的常见遗留物

即使上面都做了，还有几个地方容易藏残留：

• /usr/local/cuda目录：如果存在，里面可能是一份旧 CUDA Toolkit，即使驱动卸了，nvcc仍然可能被找到。
• ~/.bashrc或~/.profile里手动加的 PATH 和 LD_LIBRARY_PATH：很多人第一次装的时候自己加过，之后忘了删，旧路径会一直干扰新环境。
• /etc/X11/xorg.conf：如果之前配置过 NVIDIA X 设置，这个文件里可能残留显卡驱动段，后面重启直接黑屏。
• /etc/modprobe.d/里的 blacklist 文件：如果之前为了禁用 nouveau 写过 blacklist，这个文件不要删，后面还要用。

检查残留时要连隐藏文件一起看：

ls -la /usr/local/cuda*

看到cuda和cuda-11.8这两个目录名存在，就是没卸干净。再检查配置里有没有 nvidia 关键字：

grep -i nvidia /etc/X11/xorg.conf 2>/dev/null

有输出就要备份后删除。遗留问题处理完，系统才是一个「干净」的状态，接下来才能进入安装环节。

3. 桌面版最关键的转折点：禁用 nouveau 并进入纯命令行

如果你之前是在服务器版上装过 CUDA，可能会觉得桌面版多此一举。但你打开nvidia-smi之前，桌面版的显示管理器其实一直在跟你抢 GPU 资源，这才是安装失败和黑屏高发期的开始。

3.1 为什么必须禁用开源驱动 nouveau

Ubuntu 内核默认带了一个开源的 NVIDIA 显卡驱动模块，叫 nouveau。它不是不能用，而是性能和兼容性跟官方驱动差距很大。更要命的是：nouveau 加载到内核后，官方驱动安装器会检测到「NVIDIA 驱动模块已经被占用」，直接中断安装。

你可以手动确认当前是否正在用 nouveau：

lsmod | grep nouveau

只要有输出，就必须先禁用它。禁用方式是在内核模块配置里加黑名单：

sudo vim /etc/modprobe.d/blacklist-nouveau.conf

写入两行：

blacklist nouveau options nouveau modeset=0

第二行的意思是让 nouveau 不要自动接管显示输出，两者配合才能真正挡住它。保存后更新内核镜像：

sudo update-initramfs -u

这一步会重新生成 initramfs（启动时要加载的临时根文件系统），只有把它更新了，重启后 nouveau 才不会被自动加载。

3.2 桌面版和服务器版在安装时的流程差异

服务器版通常没有图形界面，你在 SSH 终端里安装即可。桌面版不一样，系统中同时存在 gdm3 或 lightdm 这样的显示管理器，它们在后台运行着 X server，假设你这时候在图形界面里点终端执行安装，安装器会提示检测到 X server running，要求你退出图形会话。

正确做法是让系统以「无图形」目标模式启动。执行：

sudo systemctl set-default multi-user.target sudo reboot

重启之后系统直接进入命令行登录界面（tty），不会启动 gdm3，也不会加载 X server。安装完 CUDA 之后，想恢复桌面，再执行：

sudo systemctl set-default graphical.target sudo reboot

注意：如果你之前已经用sudo systemctl stop gdm3临时停掉的图形服务，也可以不重启直接装，但桌面环境中残留的资源比纯命令行风险大，我一般更推荐切换 multi-user.target 后重启，这样环境干净，而且还能顺手确认重启后 nouveau 是否真的没被加载。

3.3 进入纯命令行后的自检动作

重启后你会停在字符登录界面，输入用户名密码进入 shell。这时候先做三项检查：

lsmod | grep nouveau

没有输出，说明黑名单生效了。再查 nvidia 模块是否还残留：

lsmod | grep nvidia

没有输出是正常的。然后确认显示管理器没有在运行：

systemctl status gdm3 systemctl status lightdm

如果 status 显示是 inactive (dead) 或者根本找不到服务，说明系统已经进入纯命令行模式。到这一步，安装环境才算准备好了。顺便确认网络正常，因为后面还要下载安装包，如果之前忘了下，可以在 tty 里用 wget 下载。

4. 执行 CUDA 11.8 安装：官方 runfile 的参数与日志解读

这个阶段其实是整个流程里「最顺利」的一段，但前提是参数选对。很多人安装器报错，回头翻日志才发现是驱动来源冲突或者 OpenGL 库惹的祸。

4.1 下载正确的安装包

需要去 CUDA Toolkit 11.8 的官方下载页，选择 Linux → x86_64 → Ubuntu → 20.04 → runfile (local) 格式。下载得到的是一个大文件，文件名类似：

cuda_11.8.0_520.61.05_linux.run

大约 4GB。文件名里的 520.61.05 表示捆绑的 NVIDIA 驱动版本。CUDA 11.8 对系统显卡驱动的要求是版本不能低于 520，也就是说即使你 apt 装了更高的驱动（比如 525、535 甚至 550），也不影响 CUDA Toolkit 11.8 工作。

下载完顺手做个完整性校验：

sha256sum cuda_11.8.0_520.61.05_linux.run

和官方页面给的校验值比对，一致再执行。

4.2 交互式还是静默安装：桌面版怎么选

两种方式都能用。交互式命令：

sudo sh cuda_11.8.0_520.61.05_linux.run

执行后会先弹出一段英文说明和最终用户协议，输accept接受，然后进入一个组件选择界面。你要在带空格的组件列表里去掉包含 OpenGL 库的 Item（如果选了，之后大概率黑屏），其他保持默认。这一步对新手不太友好，一不小心就误装了 OpenGL 库。

我实际用的是一行静默命令：

sudo sh cuda_11.8.0_520.61.05_linux.run \ --silent \ --toolkit \ --samples \ --no-opengl-libs

逐项解释一下：

• --silent：静默安装，不再弹交互界面。
• --toolkit：安装 CUDA Toolkit，这是核心内容，包括 nvcc、cuda runtime、cudart 等。
• --samples：顺便装官方示例代码，后面验证需要用到。
• --no-opengl-libs：不要安装 OpenGL 相关的库。

--no-opengl-libs这个参数对桌面版几乎是必选项。因为 Ubuntu 桌面本身在用 Mesa 实现 OpenGL 渲染，安装器如果覆盖成 NVIDIA 的 OpenGL 库，会导致 GNOME 渲染出问题，轻则花屏，重则重启后直接黑屏或循环登录。除非你要做 CUDA 与图形互操作（比如在 OpenGL 窗口上做渲染），否则不需要装。

如果你选择驱动走 apt、工具包走 runfile，静默命令里不需要写--driver参数，runfile 就会只装 Toolkit，不会尝试覆盖驱动。如果你决定让 runfile 连带装驱动，那就在命令里加--driver。

4.3 安装日志在哪里看，失败怎么定位

安装器执行过程中，如果机器很旧，可能会卡在某个步骤几分钟，不要急着按 Ctrl+C。如果中途报错，安装器会在终端打印一行错误摘要，通常还会指向两个日志文件：

/var/log/cuda-installer.log /var/log/nvidia-installer.log

打开日志，重点看最后几十行。常见的失败原因有三类：

1. nouveau还在运行：说明传黑名单文件没生效，或者你忘了重启。回到第 3 部分重新执行。
2. X server is running：说明显示管理器没关。确认systemctl status gdm3、lightdm都是 inactive。
3. 磁盘空间不足：runfile 解压需要大量临时空间，df -h看一下剩余空间。

这里要特别提醒：安装失败之后，不要直接再跑一次 runfile，因为第一次失败的进程可能已经在系统里留下了半个安装目录，直接重装通常会继续报错。正确做法是先把/usr/local/cuda*删掉，再重新执行安装命令。

5. 环境变量与路径：装完不等于能跑

runfile 安装完成后，你回到桌面第一件事打开终端敲nvcc --version，大概率还是提示command not found。这不是装失败了，而是新工具链的路径还没有加入你的 shell 环境。

5.1 为什么 nvidia-smi 能找到，nvcc 却找不到

先看安装目录，CUDA 11.8 默认装在这里：

ls -l /usr/local/cuda

你会看到它是一个符号链接，指向/usr/local/cuda-11.8。这个cuda链接是给开发者提供的「当前版本」入口，方便你在只需要一个版本时统一用/usr/local/cuda来引用。

但仅仅把文件放到/usr/local不够，系统不会自动去找它。你需要把 CUDA 的 bin 目录加进 PATH：

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc source ~/.bashrc

为什么我建议写进~/.bashrc而不是~/.profile？因为 Ubuntu 桌面版在图形会话里打开终端时，通常加载的是交互式非登录 shell，.profile未必会被执行，而.bashrc每次开终端都会加载。加上之后立刻source一次，当前终端就能用了。

PATH 负责让 shell 找到nvcc和nvidia-smi，LD_LIBRARY_PATH 负责让运行的程序能找到 libcuda、libcudart 这些动态链接库。只加 PATH 不加 LD_LIBRARY_PATH，编译能过，运行时可能报找不到库文件的错。

5.2 多版本 CUDA 共存与切换

如果你以后装了 CUDA 12.x，系统里会同时存在/usr/local/cuda-11.8和/usr/local/cuda-12.x两个目录。/usr/local/cuda这个链接最终会指向最新安装的那个版本，比如 12.x。但这不意味着旧版本就废了，你依然可以用绝对路径调用旧版本：

/usr/local/cuda-11.8/bin/nvcc --version

切换默认版本只需要改 PATH 里的目录名即可。比如想用 12.x 就把/usr/local/cuda-11.8/bin换成/usr/local/cuda-12.x/bin。实际项目中，我一般按项目改一个.bashrc片段或者用环境管理工具，这样可以避免全局切换影响其他项目。

一个值得注意的小坑：如果 PATH 里同时存在多个 CUDA 版本路径，nvcc --version显示的以先匹配到的为准。所以检查版本时可以用：

which nvcc

输出路径，一眼就能看出当前用的是哪个目录下的 nvcc。

5.3 重启后黑屏或循环登录：桌面版的「再看一眼」清单

这是很多人最怕面对的情况。驱动和 CUDA 都显示安装成功了，重启后登录界面输完密码，屏幕闪两下又回到登录界面，或者干脆黑屏只剩光标。我后来查看了这台机器，原因基本逃不出下面几类：

1. runfile 装驱动时没有加--no-opengl-libs，OpenGL 库被覆盖，导致图形界面初始化失败。急救办法：Ctrl+Alt+F3 切换到纯命令行 tty，登录后重新执行带--no-opengl-libs的静默安装，或者把驱动卸载干净。
2. /etc/X11/xorg.conf里有旧显卡配置残留，直接把里面 nvidia 相关的段删掉即可。
3. 内核从 5.4 升级到 5.15 后，runfile 装的驱动模块没有重新编译，模块和内核不匹配。登录到 tty，重新跑一遍驱动安装过程，或者改成 apt 驱动 + dkms 方案。
4. gdm3 本身有问题，比如缓存损坏。可以临时切换到 lightdm：

sudo apt install lightdm sudo dpkg-reconfigure lightdm

这几个是最常见的桌面版黑屏原因，按顺序排查，基本都能救回来。

6. 用实际的编译和运行来验证整条链路

前面所有工作做完，最后一步才是真正验证 CUDA 是否可用。不要只在终端打个nvcc --version就宣布成功，那只能证明编译器存在，不能证明驱动、runtime、GPU 之间的协同是通的。

6.1 三个快速命令确认

依次执行这三个命令：

nvcc --version nvidia-smi ls -l /usr/local/cuda

判断标准如下：

注意nvidia-smi输出的那一行CUDA Version: 11.8表示当前驱动支持的最高 CUDA 运行时版本，它受驱动版本影响。如果低于 11.8，说明驱动太旧，需要升级驱动；如果高于 11.8 也完全没问题，驱动是向下兼容运行时的。

6.2 编译并运行官方样例

安装时如果加了--samples，样例代码在/usr/local/cuda/samples目录。注意这个目录默认权限是 root 所有，普通用户不能直接在里面编译，最好拷贝一份到自己的工作目录：

cp -r /usr/local/cuda/samples ~/cuda-samples cd ~/cuda-samples/1_Utilities/deviceQuery make ./deviceQuery

如果之前没装build-essential，make会提示找不到cc或g++，先回去装：

sudo apt install build-essential

deviceQuery运行后，看末尾的输出：

Detected 1 CUDA Capable device(s) ... Device 0: "NVIDIA GeForce RTX 3080" CUDA Driver Version / Runtime Version 11.8 / 11.8 CUDA Capability Major/Minor version number: 8.6 ... Result = PASS

看到Result = PASS就说明整条链路已经通了：驱动正确加载、CUDA runtime 能找到设备、编译器能生成 GPU 可执行代码。

6.3 再跑一个带宽测试，确认性能没有被驱动配置拖垮

deviceQuery 只是确认可用，不确认性能。再编译一个显存带宽测试：

cd ~/cuda-samples/1_Utilities/bandwidthTest make ./bandwidthTest

正常结果会列出 Host to Device、Device to Host 和 Device to Device 三组带宽。以 GeForce RTX 3080 为例，Device to Device 大概在 800-900 GB/s 量级。如果明显低于同型号正常值，先查一下供电和散热，再考虑是不是驱动没有以性能模式启用，当然这已经超出安装范畴了。

顺便说一句，如果你还要跑 PyTorch 这类深度学习框架，装完 CUDA Toolkit 之后别忘了核对框架要求的 CUDA 版本兼容范围。PyTorch 的预编译包通常是打包了一份 CUDA runtime 的，不一定严格依赖系统 CUDA Toolkit，所以不少场景下不装系统 CUDA 也能跑；但要编译自定义 GPU 扩展、使用某些需要 nvcc 参与的工具时，系统 CUDA 11.8 就必须就位。

6.4 内核升级后的维护提示

Ubuntu 桌面版会自动更新系统内核。如果驱动是用 apt 装的，dkms 会在内核更新后自动重建驱动模块，你不用管它。如果当初图省事让 runfile 连驱动一起装了，那就需要每次内核升级后在纯命令行里重新执行一次 runfile 的驱动部分，或者干脆把/usr/local/cuda-11.8里的驱动卸载，换成 apt 方式安装驱动。

我后来给那台出问题的桌面机处理的结果是：驱动用 apt 的nvidia-driver-535装，CUDA Toolkit 用 runfile 装，两者各管各的，跑了两个多月没再黑屏，样例、训练任务全正常。桌面版 Ubuntu 装 CUDA 其实并不难，核心就在于「驱动和工具包分开管理、装前清干净、装后好好验证」这三件事，把每一步做扎实了，坑自然就少了。