最近帮一位朋友处理他 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 装。我强烈建议驱动走 aptCUDA Toolkit 走 runfile。原因有两点。第一apt 装的驱动会注册到 dkmsDynamic Kernel Module SupportLinux 内核一旦升级它会自动重新编译显卡驱动模块驱动不会丢。而 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-installernvidia-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 为什么必须禁用开源驱动 nouveauUbuntu 内核默认带了一个开源的 NVIDIA 显卡驱动模块叫 nouveau。它不是不能用而是性能和兼容性跟官方驱动差距很大。更要命的是nouveau 加载到内核后官方驱动安装器会检测到「NVIDIA 驱动模块已经被占用」直接中断安装。你可以手动确认当前是否正在用 nouveaulsmod | grep nouveau只要有输出就必须先禁用它。禁用方式是在内核模块配置里加黑名单sudo vim /etc/modprobe.d/blacklist-nouveau.conf写入两行blacklist nouveau options nouveau modeset0第二行的意思是让 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 安装日志在哪里看失败怎么定位安装器执行过程中如果机器很旧可能会卡在某个步骤几分钟不要急着按 CtrlC。如果中途报错安装器会在终端打印一行错误摘要通常还会指向两个日志文件/var/log/cuda-installer.log /var/log/nvidia-installer.log打开日志重点看最后几十行。常见的失败原因有三类nouveau还在运行说明传黑名单文件没生效或者你忘了重启。回到第 3 部分重新执行。X server is running说明显示管理器没关。确认systemctl status gdm3、lightdm都是 inactive。磁盘空间不足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 目录加进 PATHecho 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-smiLD_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 都显示安装成功了重启后登录界面输完密码屏幕闪两下又回到登录界面或者干脆黑屏只剩光标。我后来查看了这台机器原因基本逃不出下面几类runfile 装驱动时没有加--no-opengl-libsOpenGL 库被覆盖导致图形界面初始化失败。急救办法CtrlAltF3 切换到纯命令行 tty登录后重新执行带--no-opengl-libs的静默安装或者把驱动卸载干净。/etc/X11/xorg.conf里有旧显卡配置残留直接把里面 nvidia 相关的段删掉即可。内核从 5.4 升级到 5.15 后runfile 装的驱动模块没有重新编译模块和内核不匹配。登录到 tty重新跑一遍驱动安装过程或者改成 apt 驱动 dkms 方案。gdm3 本身有问题比如缓存损坏。可以临时切换到 lightdmsudo apt install lightdm sudo dpkg-reconfigure lightdm这几个是最常见的桌面版黑屏原因按顺序排查基本都能救回来。6. 用实际的编译和运行来验证整条链路前面所有工作做完最后一步才是真正验证 CUDA 是否可用。不要只在终端打个nvcc --version就宣布成功那只能证明编译器存在不能证明驱动、runtime、GPU 之间的协同是通的。6.1 三个快速命令确认依次执行这三个命令nvcc --version nvidia-smi ls -l /usr/local/cuda判断标准如下命令期望结果说明nvcc --version显示 Cuda compilation tools, release 11.8, V11.8 等字样编译器就绪nvidia-smi显示显卡型号、驱动版本、显存占用右上角显示 CUDA Version: 11.8驱动和运行时都正常ls -l /usr/local/cuda显示cuda - cuda-11.8符号链接指向正确注意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-essentialmake会提示找不到cc或g先回去装sudo apt install build-essentialdeviceQuery运行后看末尾的输出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 其实并不难核心就在于「驱动和工具包分开管理、装前清干净、装后好好验证」这三件事把每一步做扎实了坑自然就少了。