Ubuntu系统安装CUDA驱动与工具包步骤

文章导读
在 Ubuntu 上装 CUDA 环境,建议把“显卡驱动”和“CUDA Toolkit”当成两件事分开做:先用系统包管理把驱动装好,重启后确认 nvidia-smi 能正常输出,再单独安装工具包。两件事混在一个 runfile 里一次做完,出问题时很难判断坏在驱动层还是工具包层。这个顺序对物理机和云上 GPU 实例都通用,但双显卡笔记本、开启 Secure Boot、需要在容器里用 CUDA 这几
📋 目录
  1. A 先确认当前场景和目标
  2. B 按这个顺序处理
  3. C 改完后怎么验证
  4. D 容易忽略的边界
A A

在 Ubuntu 上装 CUDA 环境,建议把“显卡驱动”和“CUDA Toolkit”当成两件事分开做:先用系统包管理把驱动装好,重启后确认 nvidia-smi 能正常输出,再单独安装工具包。两件事混在一个 runfile 里一次做完,出问题时很难判断坏在驱动层还是工具包层。这个顺序对物理机和云上 GPU 实例都通用,但双显卡笔记本、开启 Secure Boot、需要在容器里用 CUDA 这几种情况,判断条件要提前补上。

先确认三件事:系统是否识别到 NVIDIA 显卡、当前是否已有驱动、目标 CUDA 版本由谁决定(框架预编译包还是自己要编译的程序)。通常做法是 apt 装驱动并重启验证 nvidia-smi,再用 runfile 只装 toolkit,接着配置 PATH/LD_LIBRARY_PATH,最后编译或跑一个样例确认。Secure Boot 未处理签名、容器缺少 runtime、驱动与工具包用两种方式混装,是最常见的失败点;出问题时应按当时的安装方式对应卸载,而不是叠加再装一遍。

先确认当前场景和目标

动手之前先把环境信息落下来,后面排查才有参照。执行下面几条命令,把输出记下来:显卡型号决定驱动分支,内核版本决定头文件包名,是否已有驱动决定要不要先清理。

lspci | grep -i nvidia
uname -r
nvidia-smi
lsmod | grep -i nouveau
df -h /usr/local

需要判断的条件主要有:
1)lspci 没有任何 NVIDIA 设备,说明是虚拟机未直通或云主机未挂载 GPU,此时装 CUDA 没有意义;
2)nvidia-smi 能出版本号,说明驱动已存在,只需要确认它是否满足目标 CUDA 版本的下限要求;
3)目标 CUDA 版本由谁定:用 PyTorch/TensorFlow 的预编译 wheel,优先按 wheel 自带的 runtime 对齐;要自己编译算子或使用 nvcc,才需要装完整 toolkit;
4)是否在容器里跑,决定要不要额外装 container toolkit;
5)是否开启 Secure Boot,决定驱动模块要不要做签名注册。

按这个顺序处理

第一步,补齐编译和内核模块依赖。内核头文件必须和 uname -r 完全对应,否则 DKMS 编译会失败:

Ubuntu系统安装CUDA驱动与工具包步骤
sudo apt update
sudo apt install -y build-essential dkms linux-headers-$(uname -r)

第二步,用 Ubuntu 仓库装驱动。先看推荐版本,再把 <版本号> 替换成实际给出的编号:

sudo ubuntu-drivers devices
sudo apt install -y nvidia-driver-<版本号>
sudo reboot

重启后先只验证驱动,不要急着往下走。第三步再装 toolkit:从 NVIDIA 下载对应版本的 runfile,安装时只选 toolkit,取消 Driver 一项,避免覆盖刚装好的驱动。<版本> 按官方下载页当前给你的文件名替换:

sudo sh cuda_<版本>_linux.run --toolkit --silent

第四步,写环境变量。建议写进 ~/.bashrc 或 /etc/profile.d/ 下的独立脚本,不要直接覆盖系统已有的 PATH:

Ubuntu系统安装CUDA驱动与工具包步骤
export PATH=/usr/local/cuda-<版本>/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-<版本>/lib64:$LD_LIBRARY_PATH

第五步,如果要在 Docker 里用 GPU,再装 container toolkit,并让 docker 重新加载配置:

sudo apt install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

改完后怎么验证

验证要分层做,每层看到的信号含义不同:

Ubuntu系统安装CUDA驱动与工具包步骤
  • 驱动层:nvidia-smi 应打印出驱动版本、CUDA 版本上限和显卡型号;报 “Failed to initialize NVML” 多数是驱动模块没加载或 Secure Boot 拦了签名。
  • 工具包层:nvcc -V 应输出 toolkit 版本,且这个版本号与你安装的目录名一致;提示 command not found 就是 PATH 没生效,先 source ~/.bashrc 再试。
  • 链接层:ldconfig -p | grep cudart 能看到 runtime 库,说明 LD_LIBRARY_PATH 或 ldconfig 配置生效。
  • 运行层:编译并执行 /usr/local/cuda-<版本>/extras/demo_suite/ 下的 deviceQuery,输出应包含 “Result = PASS”;或用 python -c "import torch; print(torch.cuda.is_available())" 看框架是否识别到设备,返回 True 才算链路通。
  • 容器层:docker run --rm --gpus all <镜像> nvidia-smi 能输出显卡信息,说明 runtime 配置正确。

容易忽略的边界

驱动版本与 CUDA 版本不是一一对应关系:驱动只提供向下兼容的运行时上限,装高于驱动支持范围的 toolkit,nvcc 能装但运行时会报 “CUDA driver version is insufficient”。反过来,框架 wheel 通常自带 CUDA runtime,只需要驱动满足下限,不必额外装完整工具包。

内核升级后,DKMS 会尝试自动重建 NVIDIA 模块;如果升级后 nvidia-smi 突然失效,先看 dkms status 和 apt install linux-headers-$(uname -r) 是否缺失,再考虑切回上一个内核启动验证。开启 Secure Boot 的机器需要在安装过程中完成 MOK 密钥注册,跳过这一步模块会加载失败。

回退时按安装方式对应处理,不要叠加:apt 装的驱动用 sudo apt purge '^nvidia-.*' '^libnvidia-.*' 加 sudo apt autoremove 清理;runfile 装的 toolkit 用 sudo /usr/local/cuda-<版本>/bin/cuda-uninstaller 或重新执行 --uninstall。双显卡笔记本(Optimus)和 WSL 环境不完全适用上面这套流程,前者涉及显卡切换与显示输出,后者走的是宿主驱动加 WSL 内工具包的路径,需要按各自方式确认,不能直接照搬。