算力机器驱动安装失败，CUDA环境排错步骤

算力机器驱动安装失败通常不是硬件坏了，而是驱动版本、内核头文件或CUDA Toolkit三者不匹配。
本文面向零基础用户，按“先查再卸再装后验”的顺序，把CUDA环境排错步骤拆成可照做的命令，最终让nvidia-smi和nvcc -V都能正常输出。

先确认失败到底卡在哪一步

不要急着重装，先看两个输出。
执行nvidia-smi，如果提示command not found，说明驱动没装或没进PATH；
如果提示NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver，说明驱动装了但内核模块没加载。

再执行uname -r查看当前内核版本，并用ls /usr/src | grep $(uname -r)检查是否安装了对应的linux-headers。
驱动安装失败最常见的原因就是内核头文件缺失或版本不一致。

如果之前用.run文件装过驱动，先执行lsmod | grep nvidia和cat /proc/driver/nvidia/version确认残留情况。
有残留时必须先卸载，否则新驱动无法正常编译。

清理旧驱动与残留配置

根据安装方式选择卸载命令。
如果是.run安装，进入原驱动目录执行：

sudo ./NVIDIA-Linux-x86_64-*.run --uninstall

如果是apt或yum安装，用包管理器卸载：

sudo apt purge nvidia-* cuda-*
sudo apt autoremove

卸载后重启机器，执行lsmod | grep nvidia确认没有输出。
如果仍有输出，说明模块被占用，可执行sudo rmmod nvidia_drm nvidia_modeset nvidia手动移除，再重启。

同时检查/etc/modprobe.d/下是否有blacklist-nouveau.conf，确保禁用开源nouveau驱动：

blacklist nouveau
options nouveau modeset=0

执行sudo update-initramfs -u更新initramfs，然后重启。

安装匹配的驱动与CUDA Toolkit

先到NVIDIA官网查当前GPU型号对应的推荐驱动版本，不要盲目装最新版。
确认版本后，安装编译依赖：

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

如果使用apt安装驱动，执行：

sudo apt install nvidia-driver-版本号

如果使用.run文件，先给执行权限并运行：

sudo chmod +x NVIDIA-Linux-x86_64-*.run
sudo ./NVIDIA-Linux-x86_64-*.run --dkms --no-opengl-files

安装过程中如果提示是否注册DKMS，选Yes；
提示是否安装32位兼容库，按需选择。
CUDA Toolkit建议用官方runfile或apt源安装，版本要与驱动兼容，具体兼容表以官方文档为准。

验证与常见报错处理

安装完成后重启，依次执行：

nvidia-smi
nvcc -V

nvidia-smi应显示GPU型号、驱动版本和CUDA版本；nvcc -V应显示CUDA编译器版本。
如果nvidia-smi报错但nvcc -V正常，说明驱动模块没加载，检查dmesg | grep nvidia看内核日志。

常见报错Failed to initialize NVML: Driver/library version mismatch表示驱动库和内核模块版本不一致，通常重启即可解决；
若重启无效，重新安装驱动并确保DKMS正常。
报错Unable to find the kernel source tree则说明内核头文件缺失，补装linux-headers-$(uname -r)后重新编译。

如果nvidia-smi正常但CUDA程序报no CUDA-capable device is detected，检查是否在容器内运行，容器需要加--gpus all参数。

排错后如何确认环境长期稳定

执行nvidia-smi -q | grep -i "driver version"和dkms status，确认驱动已注册到DKMS，这样内核升级后驱动会自动重编译。
建议固定内核版本或关闭自动内核更新，避免升级后驱动再次失效。

如果后续更换GPU或升级CUDA，先查兼容表再操作，不要直接覆盖安装。
整个CUDA环境排错步骤的核心是：版本对齐、残留清理、依赖完整、重启验证。

几个高频疑问

驱动装好后每次重启都失效怎么办？
检查/etc/modprobe.d/是否禁用了nvidia，并确认nvidia-persistenced服务已启用。执行systemctl status nvidia-persistenced查看状态。

CUDA Toolkit版本和驱动版本必须完全一致吗？
不是。驱动有最低版本要求，CUDA Toolkit版本不能高于驱动支持的上限，具体对应关系以NVIDIA官方兼容表为准。

容器里跑CUDA程序提示找不到设备？
确认已安装nvidia-container-toolkit，并在启动容器时加--gpus all，同时检查宿主机nvidia-smi是否正常。