装机这事儿说难是难在让人摸不着头脑的报错说简单其实就是一套固定的流程把它走通。最近给一台装好 Ubuntu 20.04 桌面版的工作站配 CUDA 11.8折腾了两天踩了不少坑所以把这套完整的安装思路、步骤和排查方法整理出来。只要你跟着这篇文章走一遍基本不需要再去搜索引擎里一段一段地找解决方案。这篇文章针对的是 Ubuntu 20.04 DesktopFocal Fossa配上 CUDA 11.8 的完整安装过程。为什么强调 Desktop 版本因为桌面版带图形界面驱动和显示管理器的冲突是很多问题的根源比如安装完驱动进不了桌面、黑屏、循环登录这些都是我实际踩过、也帮你提前排除掉的坑。CUDA 11.8 是一个应用非常广泛的版本很多机器学习和科学计算框架对它的支持非常成熟这也是我选择这个版本的原因。1. 安装前的环境检查与准备工作1.1 先确认你到底要不要装、要装什么很多人一上来就找教程复制命令结果装完了也不知道自己装的是什么东西。我们先花两分钟把环境摸清楚这一步能帮你避开后面一半的坑。首先是确认显卡型号。打开终端输入lspci | grep -i nvidia如果你看到类似NVIDIA Corporation GA102 [GeForce RTX 3080]这样的输出说明系统识别到了 NVIDIA 显卡。如果没有任何输出那就麻烦了可能是显卡没插好、没有供电、或者 BIOS 里没开启独立显卡。这一点在笔记本双显卡机型上尤其常见你得进 BIOS 确认显卡模式是不是也勾选了独立显卡这里就不展开讲了。然后是确认系统版本和内核版本lsb_release -a uname -r我这边输出是Ubuntu 20.04.6 LTS内核是5.15.0-XX-generic。这里要注意同一个 Ubuntu 版本内核对驱动和 CUDA 的兼容性会影响比较大。5.15 这个内核版本对 NVIDIA 驱动和 CUDA 11.8 的支持很稳定推荐使用新内核或者老内核都可能有一些奇怪的问题。最后看一下 GCC 编译器版本因为 CUDA 运行时里有一部分组件需要用到本机编译器不仅仅是 nvcc。输入gcc --versionCUDA 11.8 官方支持到 GCC 10Ubuntu 20.04 默认安装的是 GCC 9正好在支持范围内。如果你之前为了别的事情升级了 GCC 到 11、12编译 CUDA 工程时就会遇到兼容性报错后面第五节我会讲怎么处理。1.2 旧驱动和 CUDA 的清理工作如果你这台机器之前装过 NVIDIA 驱动或者 CUDA强烈建议先全部清理干净。混装新旧驱动是黑屏和循环登录的头号凶手。先查看装的什么驱动dpkg -l | grep nvidia如果有输出说明之前装过用下面的命令清理sudo apt-get purge nvidia* libnvidia* sudo apt-get autoremove对于之前用 runfile 方式装的 CUDA也要手动清理一下sudo rm -rf /usr/local/cuda*然后最好把/usr/local/下面的 cuda 目录都看一下确认清理干净了再往下走。这个步骤不能偷懒尤其是从 CUDA 10 或者 11 老版本升级到 11.8残留的库文件会让你在编译的时候遇到各种链接错误。1.3 禁用 nouveau 驱动UEFI 安全启动和显示管理器的问题Ubuntu 系统自带的nouveau是一个开源的 NVIDIA 驱动它和英伟达官方闭源驱动不兼容。如果不禁用它安装官方驱动后大概率会出现黑屏、闪屏甚至在登录界面无限循环。创建一个配置文件sudo bash -c echo -e blacklist nouveau\noptions nouveau modeset0 /etc/modprobe.d/blacklist-nouveau.conf然后再更新内核引导否则上面的配置不会生效sudo update-initramfs -u改完内核参数以后需要重启sudo reboot重启之后验证一下 nouveau 是否真的被禁用了lsmod | grep nouveau如果没有输出说明禁用生效了。这一步做完驱动安装的环境就准备好了。特别提醒如果你的机器开了 Secure Boot安全启动安装驱动的时候会被卡住提示需要签名密钥。最简单的方式是进 BIOS 把它关掉否则你要自己去弄一套 DKMS 签名流程非常繁琐。2. NVIDIA 驱动安装策略与实操2.1 驱动版本到底应该怎么选别照抄最新版装 CUDA 之前显卡驱动是第一道门槛。很多人纠结选哪个版本的驱动我在这一步也踩过坑——直接装了当时最新的 545 版本结果和 CUDA 11.8 配合时虽然能跑但编译 PyTorch 扩展的时候会出现警告性能测试的表现也不稳定。推荐的原则很简单CUDA 11.8 官方建议的最低驱动版本是 520.61.05但实际使用中 525、535 这些分支的驱动和 CUDA 11.8 配合都很稳定。你要知道驱动和 CUDA 的关系是“向下兼容”的高版本驱动可以跑低版本 CUDA反过来不行。所以你可以装相对新的驱动但不能装超过太多。用ubuntu-drivers工具检测系统推荐的版本ubuntu-drivers devices这个命令会列出你的显卡设备和可用的驱动版本还会推荐一个版本有recommended标记。但注意recommended推荐的往往是最新版本不一定是最合适的。我的做法是先去英伟达官网查 CUDA 11.8 的兼容驱动列表然后选一个在该列表范围内、又不太旧的版本安装。比如这次我装的是 535 系列驱动非常稳。2.2 安装驱动apt 方式还是 runfile 方式NVIDIA 驱动安装有两种主流方式一种是利用 Ubuntu 软件源通过 apt 安装另一种是去官网下载 runfile 手动安装。我强烈推荐 apt 方式除非你有特殊需求。apt 方式的好处是依赖关系由系统自动处理卸载方便不会残留和系统内核模块的衔接更平滑不容易出现模块加载失败执行安装sudo apt install nvidia-driver-535如果你想省事也可以直接执行sudo ubuntu-drivers autoinstall自动安装推荐版本。开启 32 位架构某些应用和 OpenGL 库需要sudo dpkg --add-architecture i386 sudo apt update安装完以后重启sudo reboot开机后验证nvidia-smi如果能正常显示显卡信息、驱动版本和 CUDA 版本号注意这里显示的 CUDA 版本只是驱动支持的版本不代表你已经装了 CUDA 11.8说明驱动安装成功了。我当时用nvidia-smi看到输出显示Driver Version: 535.XXX CUDA Version: 12.2其实心里有数这个 CUDA Version 只是个上限不是说你已经装好了 12.2。不要被它误导。2.3 驱动装完以后的黑屏自救方法很多人装完驱动以后重启卡在登录界面或者黑屏。这个问题很常见但绝大多数情况下只是因为 display manager 没有正确加载。在黑屏的界面按Ctrl Alt F2进入虚拟终端登录你的账户然后查看日志cat /var/log/Xorg.0.log | grep EE常见的原因有两种nouveau 模块没有被正确禁用重新检查lsmod | grep nouveau确保没有输出驱动和当前内核版本不匹配卸载重装驱动或者换个版本试试如果实在救不回来就在虚拟终端里卸载驱动回到老版本sudo apt purge nvidia-driver-* sudo reboot只要 nouveau 禁用的步骤没做错驱动版本不过于新这一步一般不会出问题。但备份好这个逃生通道心理压力会小很多。3. CUDA 11.8 安装全流程3.1 下载 cuda_11.8.0_linux.run这里要说一句很多人跑去 NVIDIA 官网首页下载发现最新已经是 CUDA 12.x 系列了翻半天找不到 11.8。因为 11.8 已经不是“当前版本”了你需要去官网的归档页面CUDA Toolkit Archive才能找到旧版本的链接。页面里找到 CUDA Toolkit 11.8.0选择 Linux 操作系统、x86_64 架构、Ubuntu 20.04系统会给你一个类似这样的下载命令注意我打码了一部分实际以官网为准wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run下载后建议先检查一下文件大小和 MD5 校验确保文件完整。文件大概有 3GB 左右如果太小一般是网络中断导致下载不完整运行的时候会报tar: Error is not recoverable这样的错误。3.2 runfile 安装器交互式操作要点下载完后给执行权限chmod x cuda_11.8.0_520.61.05_linux.run开始安装sudo sh cuda_11.8.0_520.61.05_linux.run这里有一系列交互式提示我把关键节点梳理一下。首先它会建议你用--toolkit只装 Toolkit 部分因为它检测到你已经有驱动了。我建议直接接受这个默认建议只安装 Toolkit因为驱动部分我们在第二步已经装好了重复安装反而可能引起版本冲突。接下来会打出一大段英文协议说明让你确认或者拒绝。这里直接输入accept按回车。然后你需要看到组件清单Component Selection在这个界面里[X] Driver这个复选框默认是选中的你必须取消它[X] CUDA Toolkit 11.8保持选中[X] CUDA Demo Suite和[X] CUDA Documentation按需选择我建议都留着后面验证用到 demo suite操作方式是按上下键移动光标按空格切换选中/取消。取消 Driver 后移到Install按回车安装过程就会开始。整个安装大概几分钟看你的硬盘读写速度。安装完成后会有提示Please make sure that PATH includes /usr/local/cuda-11.8/bin这就是告诉你下一步要配置环境变量了。3.3 配置 PATH 和 LD_LIBRARY_PATH写成软链接才是长久之计安装目录在/usr/local/cuda-11.8。为了以后多版本切换方便NVIDIA 默认会在/usr/local/cuda创建一个软链接指向cuda-11.8。如果你装的是唯一的版本可以只用/usr/local/cuda这个路径这样版本升级时不用改环境变量。配置用户级环境变量不影响系统其他用户echo export PATH/usr/local/cuda-11.8/bin:$PATH ~/.bashrc echo export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH ~/.bashrc加载配置source ~/.bashrc验证是否配置成功which nvcc nvcc --version如果which nvcc输出/usr/local/cuda-11.8/bin/nvcc说明环境变量生效了。还有一个很多人忽略的点如果你用的是 zsh要写进~/.zshrc而不是~/.bashrc。我见过有人两个都配了后来切换 shell 的时候环境变量对不上编译程序的时候老是找不到 nvcc。4. 验证安装与编译首轮测试4.1 检查 nvcc 和 nvidia-smi 的版本一致性打开终端输入nvcc --version正常输出最后会有Cuda compilation tools, release 11.8, V11.8.89说明 nvcc 编译器已经就位。同时跑一下nvidia-smi右上角显示CUDA Version: 11.8就对了这里提醒你不一定。nvidia-smi显示的 CUDA 版本是驱动支持的最高 CUDA 版本如果驱动版本是 535.xxx这里可能会显示12.2。这不影响你的 nvcc 工具链是 11.8两者不冲突。你在跑实际应用的时候程序会通过运行时 API 请求 CUDA 版本驱动只要大于等于这个版本就能正常工作。判断装没装对的唯一标准是nvcc --version输出 11.8同时nvidia-smi能正常显示显卡信息就说明工具链已经通了。4.2 编译示例程序 deviceQueryCUDA 自带的示例程序里有一个deviceQuery用来查询显卡支持的 CUDA 能力也用来验证整个工具链能不能正常编译运行。进入示例目录cd /usr/local/cuda-11.8/extras/demo_suite/执行编译sudo make或者不用 sudo直接make然后运行./deviceQuery如果输出最后包含Result PASS说明你的 CUDA 运行环境是完全正常的。如果这里失败那说明虽然 nvcc 能跑但运行时和驱动的通信有问题多半是驱动没配对。4.3 写个最小测试程序验证编译器到运行时全链路示例程序通过不代表你自己的编译环境没问题。我再习惯性地写一个最小的测试程序验证一下 nvcc 能不能编译用户代码并且能调用到各版本的运行时库。新建一个文件test.cu#include cstdio __global__ void hello_kernel() { printf(Hello from GPU thread %d\n, threadIdx.x); } int main() { hello_kernel1, 8(); cudaDeviceSynchronize(); return 0; }编译nvcc -o test test.cu运行./test如果输出 8 行Hello from GPU thread X说明 nvcc、CUDA 运行时、驱动三个环节全部正常工作。这一步其实比deviceQuery更有意义因为这模拟了你平时实际开发时遇到的环境要求。如果你连这一步都通过了那么恭喜你CUDA 11.8 安装已经彻底完成可以放心去编译 PyTorch、TensorFlow 等框架及其扩展模块了。5. 常见安装问题与排查技巧实录5.1 为什么我编译时提示找不到cuda_runtime.h这个报错和安装无关是环境变量没配好。nvcc在编译时默认会在/usr/local/cuda/include找头文件。如果你安装完 CUDA 后没有配置软链接或者软链接指向了不存在的目录就会找不到头文件。解决方式很简单ls -l /usr/local/cuda确认软链接是否存在。如果不存在手动创建sudo ln -s /usr/local/cuda-11.8 /usr/local/cuda另外一个隐蔽的问题是如果你之前手动设置了CUDA_HOME环境变量而它指向了错误的路径也会导致编译时找不到头文件。检查一下echo $CUDA_HOME最好让CUDA_HOME指向/usr/local/cuda这样以后升级版本也不会变。5.2 编译报错与 GCC 版本不兼容常见但不是大问题如果你在编译某些旧项目时出现一堆模板或者内联函数相关的报错很可能是因为 GCC 版本高于 CUDA 支持范围。CUDA 11.8 支持的 GCC 上限是 10Ubuntu 20.04 默认 GCC 是 9一般不踩雷。但有些人手动升级过 GCC比如升到 11 或 12就会遇到这种问题。最简单的处理方法是用 update-alternatives 临时切换 GCC 版本sudo apt install gcc-10 g-10 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 sudo update-alternatives --install /usr/bin/g g /usr/bin/g-10 100这里补充一句除非你有非用不可的理由否则不用升级系统默认 GCCUbuntu 20.04 自带的 GCC 9 搭配 CUDA 11.8 是官方测试过最稳的组合。5.3 安装 CUDA 时误勾选了 Driver结果驱动版本冲突runfile 安装界面默认会勾选 Driver如果你忽略了这个细节直接把 Driver 也装上了它会把已有的 apt 驱动替换成打包的 520.61 版本。这个驱动版本比较老和你 Ubuntu 20.04 内核的适配程度不如 535可能出现一些小毛病。如果发生冲突处理方式是重新安装一次自己想要的驱动版本然后确认/usr/local/cuda-11.8里面是不是只有 Toolkit。查看ls /usr/local/cuda-11.8/bin/ | grep nvcc如果正常显示nvcc再跑一下nvidia-smi确认驱动还活着基本就没问题了。所以再次提醒在 Component Selection 界面Driver那一项一定要取消勾选。5.4 循环登录问题的终极排查思路这是 NVIDIA 驱动安装最经典的问题之一。表现是你在登录界面输入密码后屏幕闪一下又回到登录界面。这一步我在第一节提到过但这里把排查思路讲完整。首先按Ctrl Alt F3进入 tty 终端登录后查看 Xorg 日志cat /var/log/Xorg.0.log | grep -i error如果有(EE) NVIDIA(0): Failed to assign any connected display devices这样的错误多半是驱动和显示器连接问题重新拔插 HDMI/DP 线或者检查是不是显卡供电不足。如果日志显示模块加载错误比如Failed to load module nvidia重新安装驱动sudo apt install --reinstall nvidia-driver-535最后如果实在排查不出来进入恢复模式使用sudo apt purge nvidia-*恢复系统再用本文第二小节的步骤重装一次即可。不要觉得循环登录是不可挽救的问题它有固定的解决路径一步一步排查就可以了。结尾补充最后分享一点个人经验装完 CUDA 不是终点而是开始。真正干活的时候你会发现光有工具链远远不够——还要适配深度学习框架、装 cuDNN、管理 NCCL这些后续配置每一个都可能踩坑。但这一切的前提是你的 CUDA 基础装得足够干净、足够稳定。我个人在实际安装中最大的体会是装驱动时不要贪新、装 CUDA 时不要贪全、配置环境变量时不要贪多。一步步来每装完一个环节就验证一次即使中间出了问题你也能立刻定位到是哪一步出错。别像我第一次那样一股脑全装完黑屏之后完全不知道从哪开始排查只能重装系统。最后再分享一个小技巧在你成功安装完驱动和 CUDA 之后给系统做一次快照或者备份。比如用 TimeShift 做一个系统备份以后不管怎么折腾一条命令就能还原到当前这个干净的状态。这套流程加上备份方法足够应付实验室、公司环境里大部分深度学习开发机的部署需求了。
