1. 环境准备与版本选型别急着敲命令先把账算清楚装 CUDA 这件事十个新手有九个栽在第一步——版本没对齐。我见过太多人上来就sudo apt install nvidia-cuda-toolkit装完发现 PyTorch 跑不起来回头查半天才发现驱动版本和 CUDA 版本压根不匹配。所以这一节咱们不聊命令先把版本关系捋顺。1.1 驱动版本、CUDA 版本、框架版本的三层依赖关系这三者的关系可以用一个生活化的类比来理解显卡驱动是地基CUDA Toolkit 是楼体框架PyTorch/TensorFlow 是精装修。地基没打好楼体就歪楼体歪了装修再漂亮也住不了人。具体来说NVIDIA 驱动有一个“最高支持的 CUDA 版本”。比如驱动版本 550.144.03它最高支持到 CUDA 12.4。你可以在 CUDA Toolkit 的官方 Release Notes 里找到这张对应表也可以在装完驱动后用nvidia-smi命令直接看右上角显示的“CUDA Version”——注意这个显示的是驱动能支持的最高 CUDA 版本不是你当前安装的 CUDA 版本。很多人在这里犯迷糊nvidia-smi显示 CUDA 12.4就以为自己已经装了 CUDA 12.4。其实不是那只是驱动能力的上限。你真正装的 CUDA 版本要用nvcc --version来看。那为什么版本要对齐因为 PyTorch 这类框架在编译时是链接到特定 CUDA 版本的。比如 PyTorch 2.1 官方 wheel 包默认编译时用的是 CUDA 12.1你如果装的是 CUDA 11.8虽然驱动向下兼容但框架找不到对应的动态库就会报libcudart.so.12: cannot open shared object file这类错误。我一般建议按这个顺序倒推先确定你要用的深度学习框架版本比如 TensorFlow 2.5.0 或 PyTorch 2.1查这个框架官方文档推荐的 CUDA 和 cuDNN 版本组合根据 CUDA 版本反推需要的驱动最低版本最后去装驱动提示TensorFlow 2.5.0 这个版本比较特殊它官方要求的是 CUDA 11.2 cuDNN 8.1但 CUDA 11.2 在较新的 Ubuntu 22.04 上安装会有 GCC 版本兼容问题。实际社区验证下来CUDA 11.8 cuDNN 8.6 也能跑但需要手动处理一些符号链接。如果你不是非 2.5.0 不可建议直接上 TensorFlow 2.13 配 CUDA 11.8省心很多。1.2 不同显卡型号的 CUDA 支持上限另一个容易被忽略的点是显卡本身的算力等级Compute Capability。每张 N 卡都有一个算力值比如 RTX 4060 Ti 是 8.9RTX 3090 是 8.6GTX 1080 Ti 是 6.1。CUDA Toolkit 在编译时会针对不同的算力架构生成代码新版本 CUDA 会逐步淘汰对老架构的支持。举个例子CUDA 12.x 已经不再支持算力 3.5 及以下的显卡比如 GTX 780 这类 Kepler 架构。而 RTX 4060 Ti 这种 Ada Lovelace 架构的卡算力 8.9需要 CUDA 11.8 及以上才能完整支持。如果你给 4060 Ti 装 CUDA 11.4虽然能装上但编译出来的程序可能无法充分利用新架构的特性性能会打折扣。所以选版本的时候先查一下自己显卡的算力值再去 CUDA 官方文档确认这个算力从哪个版本开始被支持、到哪个版本被淘汰。这个信息在 CUDA GPU 支持列表里写得很清楚。1.3 多版本共存的必要性做深度学习的人迟早会遇到这个场景论文复现需要 PyTorch 1.7 CUDA 10.2但新项目要用 PyTorch 2.1 CUDA 12.1。你不可能每次切换项目就重装一次 CUDA所以多版本共存是刚需。CUDA 的多版本共存其实很简单因为它的安装目录默认就是带版本号的/usr/local/cuda-11.8、/usr/local/cuda-12.1。你只需要通过环境变量PATH和LD_LIBRARY_PATH来切换当前使用的版本就行。具体怎么操作我在第三节会详细讲。2. 驱动安装实操从禁用 nouveau 到验证 nvidia-smi驱动安装是整个流程里最容易翻车的一步尤其是在 Linux 桌面环境下。我踩过的坑包括装完驱动进不了图形界面、nvidia-smi 报“No devices were found”、系统重启后黑屏等等。这一节把完整流程和避坑点都过一遍。2.1 安装前的系统检查与准备在动手之前先做三件事第一确认显卡型号和当前驱动状态。用lspci | grep -i nvidia看系统有没有识别到 N 卡。如果这条命令没输出说明硬件层面就没认到可能是卡没插好或者 BIOS 里没启用。第二检查是否已安装开源驱动 nouveau。Ubuntu 默认会加载 nouveau 这个开源驱动它和 N 卡官方驱动冲突必须先禁用。用lsmod | grep nouveau检查如果有输出就需要手动禁用。禁用方法是在/etc/modprobe.d/下创建一个配置文件sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nouveau.conf sudo update-initramfs -u然后重启系统。重启后再用lsmod | grep nouveau确认没有输出才算是禁用成功。第三确认 GCC 和内核头文件已安装。N 卡驱动安装时需要编译内核模块所以需要gcc、make和对应内核版本的linux-headers。用sudo apt install build-essential linux-headers-$(uname -r)一把装齐。注意如果你用的是 WSL2情况不太一样。WSL2 不需要在 Linux 侧装驱动驱动是装在 Windows 宿主机的。你只需要在 Windows 上装好 N 卡驱动WSL2 里就能直接用nvidia-smi。但 CUDA Toolkit 还是要装在 WSL2 的 Linux 发行版里。这个后面会单独讲。2.2 驱动安装的三种方式与选型建议装 N 卡驱动有三种主流方式各有优劣安装方式优点缺点适用场景系统包管理器apt简单自动处理依赖版本通常较旧新手不追求最新版官方 .run 文件版本最新可控性强需要手动禁用 nouveau容易翻车需要特定版本官方 CUDA 仓库版本较新apt 管理需要添加第三方源推荐平衡了易用性和版本我个人最推荐第三种通过 NVIDIA 官方 CUDA 仓库来装。这样既能拿到较新的版本又能用 apt 管理依赖卸载也干净。具体操作# 添加 NVIDIA 官方 GPG key 和仓库 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update # 安装驱动以 550 版本为例 sudo apt install nvidia-driver-550装完后重启系统。重启后运行nvidia-smi如果能看到显卡信息表格说明驱动装好了。2.3 nvidia-smi 输出解读与常见报错nvidia-smi是验证驱动是否正常工作的第一道关卡。正常输出会包含这些关键信息Driver Version驱动版本号比如 550.144.03CUDA Version驱动支持的最高 CUDA 版本比如 12.4GPU 名称显卡型号显存使用情况Total / Used / FreeGPU 利用率当前算力占用百分比运行中的进程哪些程序在用显卡如果nvidia-smi报错常见的有这几种报错一NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver这通常意味着驱动没装好或者内核模块没加载。排查步骤先用lsmod | grep nvidia看模块有没有加载如果没有用sudo modprobe nvidia手动加载试试如果还不行检查dmesg | grep -i nvidia看内核日志里有没有报错。报错二No devices were found这个多半是 nouveau 没禁用干净或者显卡被其他驱动占用了。回到 2.1 节确认 nouveau 已禁用然后重启。报错三Failed to initialize NVML: Driver/library version mismatch这是驱动版本和内核模块版本不一致导致的通常发生在你刚更新了驱动但没重启的时候。解决办法很简单重启系统。实操心得每次装完驱动或更新驱动一定要重启。我见过太多人装完驱动不重启然后对着报错折腾半天最后重启一下就好了。这个时间省不得。3. CUDA Toolkit 安装runfile 还是 deb选对方式少走弯路驱动装好之后接下来就是 CUDA Toolkit。这里有个概念要区分清楚驱动和 CUDA Toolkit 是两回事。驱动是让系统能识别和使用显卡CUDA Toolkit 是提供编译和运行 CUDA 程序的工具链包括nvcc编译器、各种库文件、头文件等。3.1 CUDA Toolkit 的两种安装方式对比NVIDIA 官方提供两种主要的安装方式deb 包安装通过 apt 管理安装到系统默认路径会自动处理依赖。优点是简单缺点是版本切换麻烦而且有时候 apt 会自动更新 CUDA 版本导致和框架不匹配。runfile 安装下载一个.run可执行文件运行后进入交互式安装界面。优点是可以自定义安装路径、可以选择不安装驱动因为驱动已经装过了、可以精确控制安装组件。缺点是需要手动处理一些依赖。我一般推荐用 runfile 方式因为它对多版本共存更友好。安装时注意这几点在安装选项中取消勾选 Driver因为驱动已经单独装过了安装路径保持默认的/usr/local/cuda-版本号不要勾选创建/usr/local/cuda软链接这个软链接我们后面手动管理方便切换版本安装命令示例wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run运行后会先解压然后进入一个文本界面。注意把 Driver 那一项的勾去掉只保留 CUDA Toolkit 相关的组件。3.2 环境变量配置与多版本切换装完 CUDA 后需要配置环境变量才能让系统找到nvcc等工具。在~/.bashrc或~/.zshrc里添加export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH然后source ~/.bashrc生效。用nvcc --version验证如果输出了版本信息说明配置成功。如果你装了多个 CUDA 版本切换的方法就是改这两行环境变量里的版本号。但每次手动改太麻烦我一般会写两个 aliasalias cuda11export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH alias cuda12export PATH/usr/local/cuda-12.1/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH这样在终端里敲cuda11或cuda12就能快速切换。注意nvcc的版本和nvidia-smi显示的 CUDA 版本是两回事。nvcc显示的是你当前 PATH 里指向的 CUDA Toolkit 版本nvidia-smi显示的是驱动支持的最高版本。两者可以不一致只要 Toolkit 版本不超过驱动支持的上限就行。3.3 nvcc 不是内部或外部命令的排查思路这个报错在 Windows 和 Linux 上都常见本质就是系统找不到nvcc这个可执行文件。排查思路分三步第一步确认 CUDA Toolkit 是否真的装了。去/usr/local/下看有没有cuda-xx.x目录。如果没有说明 Toolkit 没装成功回去重新装。第二步确认 PATH 是否配置正确。用echo $PATH看输出里有没有 CUDA 的 bin 目录。如果没有检查~/.bashrc里的配置确认source过了。第三步确认 nvcc 文件是否存在且有执行权限。用ls -l /usr/local/cuda-11.8/bin/nvcc检查。如果文件不存在可能是安装时没勾选 Toolkit 组件如果没有执行权限用chmod x加上。在 Windows 上这个报错通常是因为 CUDA 的 bin 目录没加到系统环境变量 Path 里。默认路径是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin把它加到 Path 里重启终端就好了。4. cuDNN 安装最容易被忽略的细节cuDNN 是 NVIDIA 的深度神经网络加速库PyTorch 和 TensorFlow 的 GPU 版本都依赖它。但 cuDNN 的安装方式和 CUDA 不太一样它不需要运行安装程序本质上就是把几个文件复制到 CUDA 的对应目录里。4.1 cuDNN 版本选择与下载cuDNN 的版本必须和 CUDA 版本严格对应。比如 CUDA 11.8 需要 cuDNN 8.6.xCUDA 12.1 需要 cuDNN 8.9.x。下载页面会明确标注每个 cuDNN 版本支持的 CUDA 版本选的时候看清楚。下载需要注册 NVIDIA 开发者账号登录后才能看到下载链接。下载下来通常是一个 tar.gz 压缩包解压后包含include、lib、bin三个目录。4.2 手动复制文件与权限设置安装 cuDNN 就是把这三个目录里的文件复制到 CUDA 安装目录的对应位置tar -xzvf cudnn-linux-x86_64-8.6.0.163_cuda11-archive.tar.xz cd cudnn-linux-x86_64-8.6.0.163_cuda11-archive sudo cp include/cudnn*.h /usr/local/cuda-11.8/include/ sudo cp lib/libcudnn* /usr/local/cuda-11.8/lib64/ sudo chmod ar /usr/local/cuda-11.8/include/cudnn*.h sudo chmod ar /usr/local/cuda-11.8/lib64/libcudnn*复制完用cat /usr/local/cuda-11.8/include/cudnn_version.h | grep CUDNN_MAJOR -A 2验证版本。实操心得cuDNN 的文件复制过去后如果之前已经编译过 PyTorch 程序可能需要清理一下编译缓存否则可能还是链接到旧版本的库。我一般会删掉~/.cache/torch目录让它重新编译。4.3 验证 cuDNN 是否生效最直接的验证方式是在 Python 里跑一段代码import torch print(torch.backends.cudnn.version()) print(torch.cuda.is_available())如果输出了 cuDNN 版本号并且is_available()返回True说明 cuDNN 和 CUDA 都配置好了。5. WSL2 下的 CUDA 安装和原生 Linux 有什么不同WSL2 是现在很多人在 Windows 上做深度学习的选择它的 CUDA 安装流程和原生 Linux 有几点关键区别。5.1 WSL2 的驱动架构与安装位置WSL2 的显卡驱动是装在 Windows 宿主机的不是装在 WSL2 的 Linux 发行版里。你只需要在 Windows 上装好 N 卡驱动建议用最新版WSL2 里就能直接用。在 WSL2 终端里运行nvidia-smi如果能看到显卡信息说明驱动层面已经通了。但 CUDA Toolkit 还是要装在 WSL2 的 Linux 里。安装方式和原生 Linux 一样用 runfile 或 apt 都行。注意 WSL2 不支持.run文件里的驱动安装部分所以安装时一定要取消勾选 Driver。5.2 WSL2 常见问题与排查问题一nvidia-smi在 WSL2 里找不到命令。这是因为 WSL2 里没有装驱动nvidia-smi是从 Windows 侧映射过来的。确认 Windows 驱动装好了然后在 WSL2 里用/usr/lib/wsl/lib/nvidia-smi试试。如果这个路径下有把它加到 PATH 里就行。问题二CUDA 程序报libcuda.so not found。WSL2 的libcuda.so在/usr/lib/wsl/lib/下需要把这个路径加到LD_LIBRARY_PATH里。问题三显存显示不对。WSL2 里nvidia-smi显示的显存是 Windows 侧分配的可能和实际显卡显存有出入。这是 WSL2 的机制决定的不影响使用。6. 常见问题速查与避坑指南这一节把前面散落的排查技巧集中整理成速查表方便遇到问题时快速定位。问题现象可能原因排查命令解决方案nvidia-smi 报通信失败驱动未加载lsmod | grep nvidiasudo modprobe nvidia或重启nvidia-smi 报版本不匹配驱动更新后未重启dmesg | grep -i nvidia重启系统nvcc 不是内部或外部命令PATH 未配置echo $PATH添加 CUDA bin 到 PATHPyTorch 报 libcudart 找不到CUDA 版本不匹配python -c import torch; print(torch.version.cuda)重装对应版本的 PyTorchcuDNN 版本不生效文件未复制到正确位置cat cudnn_version.h | grep MAJOR重新复制并设置权限多版本切换后 nvcc 版本不对环境变量顺序问题which nvcc调整 PATH 中 CUDA 路径的顺序WSL2 里找不到 nvidia-smi未映射 Windows 驱动ls /usr/lib/wsl/lib/添加路径到 PATH避坑技巧装 CUDA 之前先用sudo apt-mark hold把驱动和 CUDA 相关的包锁定版本防止系统自动更新导致版本错乱。这个操作在 Ubuntu 上尤其重要因为 unattended-upgrades 可能会在你不知情的情况下更新驱动。7. 版本迁移与升级从旧环境平滑过渡有时候你不是从零开始装而是要把旧环境的 CUDA 版本升级或迁移。比如从 CUDA 10.2 升到 11.8或者把一台机器上的环境复制到另一台。7.1 升级 CUDA 的正确姿势升级 CUDA 不建议直接覆盖安装而是装一个新版本然后通过环境变量切换。这样万一新版本有问题可以随时切回旧版本。步骤是先装新版本 CUDA Toolkit 到/usr/local/cuda-新版本然后装对应版本的 cuDNN最后改环境变量指向新版本。验证没问题后再考虑是否删除旧版本。7.2 环境迁移的注意事项把环境从一台机器迁移到另一台最容易出问题的是驱动版本不一致。如果目标机器的驱动版本低于源机器可能无法支持相同的 CUDA 版本。所以迁移前先确认目标机器的驱动版本必要时先升级驱动。另外Python 虚拟环境里的包不建议直接复制最好用pip freeze requirements.txt导出依赖列表在目标机器上重新安装。因为有些包在编译时会链接到特定路径的 CUDA 库直接复制可能路径对不上。8. 验证与性能测试装完不是终点装完 CUDA 和 cuDNN 之后跑一个简单的测试来验证整个链路是否通畅。8.1 用 CUDA Samples 做冒烟测试CUDA Toolkit 自带了一些示例程序在/usr/local/cuda-11.8/samples/下如果安装时勾选了 Samples。编译并运行deviceQuery这个示例cd /usr/local/cuda-11.8/samples/1_Utilities/deviceQuery sudo make ./deviceQuery如果输出里显示Result PASS说明 CUDA 环境完全正常。注意新版 CUDA Toolkit 的 runfile 安装包里可能不再包含 Samples需要单独从 GitHub 上克隆。如果找不到 samples 目录去 NVIDIA/cuda-samples 仓库下载对应版本的代码。8.2 用 PyTorch 做实际负载测试冒烟测试通过后用 PyTorch 跑一个实际的矩阵运算确认 GPU 能被框架正常调用import torch device torch.device(cuda if torch.cuda.is_available() else cpu) x torch.randn(1000, 1000).to(device) y torch.randn(1000, 1000).to(device) z torch.mm(x, y) print(z.device) print(torch.cuda.get_device_name(0))如果输出显示cuda:0和显卡型号说明整个链路——驱动、CUDA、cuDNN、PyTorch——全部打通了。我个人在实际操作中的体会是装 CUDA 环境这件事80% 的时间花在排查版本兼容性上20% 的时间才是真正的安装操作。所以与其急着敲命令不如先把版本对应关系查清楚把驱动和 Toolkit 的版本对齐后面会省很多事。另外每次改动驱动或 CUDA 版本后记得重启系统这个习惯能帮你避开至少一半的玄学报错。 
长河君 · 2026/10/27 3:39:42 · 阅读 1.2k CUDA环境搭建避坑指南：驱动、CUDA Toolkit与cuDNN版本对齐实战
1. 环境准备与版本选型别急着敲命令先把账算清楚装 CUDA 这件事十个新手有九个栽在第一步——版本没对齐。我见过太多人上来就sudo apt install nvidia-cuda-toolkit装完发现 PyTorch 跑不起来回头查半天才发现驱动版本和 CUDA 版本压根不匹配。所以这一节咱们不聊命令先把版本关系捋顺。1.1 驱动版本、CUDA 版本、框架版本的三层依赖关系这三者的关系可以用一个生活化的类比来理解显卡驱动是地基CUDA Toolkit 是楼体框架PyTorch/TensorFlow 是精装修。地基没打好楼体就歪楼体歪了装修再漂亮也住不了人。具体来说NVIDIA 驱动有一个“最高支持的 CUDA 版本”。比如驱动版本 550.144.03它最高支持到 CUDA 12.4。你可以在 CUDA Toolkit 的官方 Release Notes 里找到这张对应表也可以在装完驱动后用nvidia-smi命令直接看右上角显示的“CUDA Version”——注意这个显示的是驱动能支持的最高 CUDA 版本不是你当前安装的 CUDA 版本。很多人在这里犯迷糊nvidia-smi显示 CUDA 12.4就以为自己已经装了 CUDA 12.4。其实不是那只是驱动能力的上限。你真正装的 CUDA 版本要用nvcc --version来看。那为什么版本要对齐因为 PyTorch 这类框架在编译时是链接到特定 CUDA 版本的。比如 PyTorch 2.1 官方 wheel 包默认编译时用的是 CUDA 12.1你如果装的是 CUDA 11.8虽然驱动向下兼容但框架找不到对应的动态库就会报libcudart.so.12: cannot open shared object file这类错误。我一般建议按这个顺序倒推先确定你要用的深度学习框架版本比如 TensorFlow 2.5.0 或 PyTorch 2.1查这个框架官方文档推荐的 CUDA 和 cuDNN 版本组合根据 CUDA 版本反推需要的驱动最低版本最后去装驱动提示TensorFlow 2.5.0 这个版本比较特殊它官方要求的是 CUDA 11.2 cuDNN 8.1但 CUDA 11.2 在较新的 Ubuntu 22.04 上安装会有 GCC 版本兼容问题。实际社区验证下来CUDA 11.8 cuDNN 8.6 也能跑但需要手动处理一些符号链接。如果你不是非 2.5.0 不可建议直接上 TensorFlow 2.13 配 CUDA 11.8省心很多。1.2 不同显卡型号的 CUDA 支持上限另一个容易被忽略的点是显卡本身的算力等级Compute Capability。每张 N 卡都有一个算力值比如 RTX 4060 Ti 是 8.9RTX 3090 是 8.6GTX 1080 Ti 是 6.1。CUDA Toolkit 在编译时会针对不同的算力架构生成代码新版本 CUDA 会逐步淘汰对老架构的支持。举个例子CUDA 12.x 已经不再支持算力 3.5 及以下的显卡比如 GTX 780 这类 Kepler 架构。而 RTX 4060 Ti 这种 Ada Lovelace 架构的卡算力 8.9需要 CUDA 11.8 及以上才能完整支持。如果你给 4060 Ti 装 CUDA 11.4虽然能装上但编译出来的程序可能无法充分利用新架构的特性性能会打折扣。所以选版本的时候先查一下自己显卡的算力值再去 CUDA 官方文档确认这个算力从哪个版本开始被支持、到哪个版本被淘汰。这个信息在 CUDA GPU 支持列表里写得很清楚。1.3 多版本共存的必要性做深度学习的人迟早会遇到这个场景论文复现需要 PyTorch 1.7 CUDA 10.2但新项目要用 PyTorch 2.1 CUDA 12.1。你不可能每次切换项目就重装一次 CUDA所以多版本共存是刚需。CUDA 的多版本共存其实很简单因为它的安装目录默认就是带版本号的/usr/local/cuda-11.8、/usr/local/cuda-12.1。你只需要通过环境变量PATH和LD_LIBRARY_PATH来切换当前使用的版本就行。具体怎么操作我在第三节会详细讲。2. 驱动安装实操从禁用 nouveau 到验证 nvidia-smi驱动安装是整个流程里最容易翻车的一步尤其是在 Linux 桌面环境下。我踩过的坑包括装完驱动进不了图形界面、nvidia-smi 报“No devices were found”、系统重启后黑屏等等。这一节把完整流程和避坑点都过一遍。2.1 安装前的系统检查与准备在动手之前先做三件事第一确认显卡型号和当前驱动状态。用lspci | grep -i nvidia看系统有没有识别到 N 卡。如果这条命令没输出说明硬件层面就没认到可能是卡没插好或者 BIOS 里没启用。第二检查是否已安装开源驱动 nouveau。Ubuntu 默认会加载 nouveau 这个开源驱动它和 N 卡官方驱动冲突必须先禁用。用lsmod | grep nouveau检查如果有输出就需要手动禁用。禁用方法是在/etc/modprobe.d/下创建一个配置文件sudo bash -c echo blacklist nouveau /etc/modprobe.d/blacklist-nouveau.conf sudo bash -c echo options nouveau modeset0 /etc/modprobe.d/blacklist-nouveau.conf sudo update-initramfs -u然后重启系统。重启后再用lsmod | grep nouveau确认没有输出才算是禁用成功。第三确认 GCC 和内核头文件已安装。N 卡驱动安装时需要编译内核模块所以需要gcc、make和对应内核版本的linux-headers。用sudo apt install build-essential linux-headers-$(uname -r)一把装齐。注意如果你用的是 WSL2情况不太一样。WSL2 不需要在 Linux 侧装驱动驱动是装在 Windows 宿主机的。你只需要在 Windows 上装好 N 卡驱动WSL2 里就能直接用nvidia-smi。但 CUDA Toolkit 还是要装在 WSL2 的 Linux 发行版里。这个后面会单独讲。2.2 驱动安装的三种方式与选型建议装 N 卡驱动有三种主流方式各有优劣安装方式优点缺点适用场景系统包管理器apt简单自动处理依赖版本通常较旧新手不追求最新版官方 .run 文件版本最新可控性强需要手动禁用 nouveau容易翻车需要特定版本官方 CUDA 仓库版本较新apt 管理需要添加第三方源推荐平衡了易用性和版本我个人最推荐第三种通过 NVIDIA 官方 CUDA 仓库来装。这样既能拿到较新的版本又能用 apt 管理依赖卸载也干净。具体操作# 添加 NVIDIA 官方 GPG key 和仓库 wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb sudo dpkg -i cuda-keyring_1.1-1_all.deb sudo apt update # 安装驱动以 550 版本为例 sudo apt install nvidia-driver-550装完后重启系统。重启后运行nvidia-smi如果能看到显卡信息表格说明驱动装好了。2.3 nvidia-smi 输出解读与常见报错nvidia-smi是验证驱动是否正常工作的第一道关卡。正常输出会包含这些关键信息Driver Version驱动版本号比如 550.144.03CUDA Version驱动支持的最高 CUDA 版本比如 12.4GPU 名称显卡型号显存使用情况Total / Used / FreeGPU 利用率当前算力占用百分比运行中的进程哪些程序在用显卡如果nvidia-smi报错常见的有这几种报错一NVIDIA-SMI has failed because it couldnt communicate with the NVIDIA driver这通常意味着驱动没装好或者内核模块没加载。排查步骤先用lsmod | grep nvidia看模块有没有加载如果没有用sudo modprobe nvidia手动加载试试如果还不行检查dmesg | grep -i nvidia看内核日志里有没有报错。报错二No devices were found这个多半是 nouveau 没禁用干净或者显卡被其他驱动占用了。回到 2.1 节确认 nouveau 已禁用然后重启。报错三Failed to initialize NVML: Driver/library version mismatch这是驱动版本和内核模块版本不一致导致的通常发生在你刚更新了驱动但没重启的时候。解决办法很简单重启系统。实操心得每次装完驱动或更新驱动一定要重启。我见过太多人装完驱动不重启然后对着报错折腾半天最后重启一下就好了。这个时间省不得。3. CUDA Toolkit 安装runfile 还是 deb选对方式少走弯路驱动装好之后接下来就是 CUDA Toolkit。这里有个概念要区分清楚驱动和 CUDA Toolkit 是两回事。驱动是让系统能识别和使用显卡CUDA Toolkit 是提供编译和运行 CUDA 程序的工具链包括nvcc编译器、各种库文件、头文件等。3.1 CUDA Toolkit 的两种安装方式对比NVIDIA 官方提供两种主要的安装方式deb 包安装通过 apt 管理安装到系统默认路径会自动处理依赖。优点是简单缺点是版本切换麻烦而且有时候 apt 会自动更新 CUDA 版本导致和框架不匹配。runfile 安装下载一个.run可执行文件运行后进入交互式安装界面。优点是可以自定义安装路径、可以选择不安装驱动因为驱动已经装过了、可以精确控制安装组件。缺点是需要手动处理一些依赖。我一般推荐用 runfile 方式因为它对多版本共存更友好。安装时注意这几点在安装选项中取消勾选 Driver因为驱动已经单独装过了安装路径保持默认的/usr/local/cuda-版本号不要勾选创建/usr/local/cuda软链接这个软链接我们后面手动管理方便切换版本安装命令示例wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run sudo sh cuda_11.8.0_520.61.05_linux.run运行后会先解压然后进入一个文本界面。注意把 Driver 那一项的勾去掉只保留 CUDA Toolkit 相关的组件。3.2 环境变量配置与多版本切换装完 CUDA 后需要配置环境变量才能让系统找到nvcc等工具。在~/.bashrc或~/.zshrc里添加export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH然后source ~/.bashrc生效。用nvcc --version验证如果输出了版本信息说明配置成功。如果你装了多个 CUDA 版本切换的方法就是改这两行环境变量里的版本号。但每次手动改太麻烦我一般会写两个 aliasalias cuda11export PATH/usr/local/cuda-11.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-11.8/lib64:$LD_LIBRARY_PATH alias cuda12export PATH/usr/local/cuda-12.1/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH这样在终端里敲cuda11或cuda12就能快速切换。注意nvcc的版本和nvidia-smi显示的 CUDA 版本是两回事。nvcc显示的是你当前 PATH 里指向的 CUDA Toolkit 版本nvidia-smi显示的是驱动支持的最高版本。两者可以不一致只要 Toolkit 版本不超过驱动支持的上限就行。3.3 nvcc 不是内部或外部命令的排查思路这个报错在 Windows 和 Linux 上都常见本质就是系统找不到nvcc这个可执行文件。排查思路分三步第一步确认 CUDA Toolkit 是否真的装了。去/usr/local/下看有没有cuda-xx.x目录。如果没有说明 Toolkit 没装成功回去重新装。第二步确认 PATH 是否配置正确。用echo $PATH看输出里有没有 CUDA 的 bin 目录。如果没有检查~/.bashrc里的配置确认source过了。第三步确认 nvcc 文件是否存在且有执行权限。用ls -l /usr/local/cuda-11.8/bin/nvcc检查。如果文件不存在可能是安装时没勾选 Toolkit 组件如果没有执行权限用chmod x加上。在 Windows 上这个报错通常是因为 CUDA 的 bin 目录没加到系统环境变量 Path 里。默认路径是C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v11.8\bin把它加到 Path 里重启终端就好了。4. cuDNN 安装最容易被忽略的细节cuDNN 是 NVIDIA 的深度神经网络加速库PyTorch 和 TensorFlow 的 GPU 版本都依赖它。但 cuDNN 的安装方式和 CUDA 不太一样它不需要运行安装程序本质上就是把几个文件复制到 CUDA 的对应目录里。4.1 cuDNN 版本选择与下载cuDNN 的版本必须和 CUDA 版本严格对应。比如 CUDA 11.8 需要 cuDNN 8.6.xCUDA 12.1 需要 cuDNN 8.9.x。下载页面会明确标注每个 cuDNN 版本支持的 CUDA 版本选的时候看清楚。下载需要注册 NVIDIA 开发者账号登录后才能看到下载链接。下载下来通常是一个 tar.gz 压缩包解压后包含include、lib、bin三个目录。4.2 手动复制文件与权限设置安装 cuDNN 就是把这三个目录里的文件复制到 CUDA 安装目录的对应位置tar -xzvf cudnn-linux-x86_64-8.6.0.163_cuda11-archive.tar.xz cd cudnn-linux-x86_64-8.6.0.163_cuda11-archive sudo cp include/cudnn*.h /usr/local/cuda-11.8/include/ sudo cp lib/libcudnn* /usr/local/cuda-11.8/lib64/ sudo chmod ar /usr/local/cuda-11.8/include/cudnn*.h sudo chmod ar /usr/local/cuda-11.8/lib64/libcudnn*复制完用cat /usr/local/cuda-11.8/include/cudnn_version.h | grep CUDNN_MAJOR -A 2验证版本。实操心得cuDNN 的文件复制过去后如果之前已经编译过 PyTorch 程序可能需要清理一下编译缓存否则可能还是链接到旧版本的库。我一般会删掉~/.cache/torch目录让它重新编译。4.3 验证 cuDNN 是否生效最直接的验证方式是在 Python 里跑一段代码import torch print(torch.backends.cudnn.version()) print(torch.cuda.is_available())如果输出了 cuDNN 版本号并且is_available()返回True说明 cuDNN 和 CUDA 都配置好了。5. WSL2 下的 CUDA 安装和原生 Linux 有什么不同WSL2 是现在很多人在 Windows 上做深度学习的选择它的 CUDA 安装流程和原生 Linux 有几点关键区别。5.1 WSL2 的驱动架构与安装位置WSL2 的显卡驱动是装在 Windows 宿主机的不是装在 WSL2 的 Linux 发行版里。你只需要在 Windows 上装好 N 卡驱动建议用最新版WSL2 里就能直接用。在 WSL2 终端里运行nvidia-smi如果能看到显卡信息说明驱动层面已经通了。但 CUDA Toolkit 还是要装在 WSL2 的 Linux 里。安装方式和原生 Linux 一样用 runfile 或 apt 都行。注意 WSL2 不支持.run文件里的驱动安装部分所以安装时一定要取消勾选 Driver。5.2 WSL2 常见问题与排查问题一nvidia-smi在 WSL2 里找不到命令。这是因为 WSL2 里没有装驱动nvidia-smi是从 Windows 侧映射过来的。确认 Windows 驱动装好了然后在 WSL2 里用/usr/lib/wsl/lib/nvidia-smi试试。如果这个路径下有把它加到 PATH 里就行。问题二CUDA 程序报libcuda.so not found。WSL2 的libcuda.so在/usr/lib/wsl/lib/下需要把这个路径加到LD_LIBRARY_PATH里。问题三显存显示不对。WSL2 里nvidia-smi显示的显存是 Windows 侧分配的可能和实际显卡显存有出入。这是 WSL2 的机制决定的不影响使用。6. 常见问题速查与避坑指南这一节把前面散落的排查技巧集中整理成速查表方便遇到问题时快速定位。问题现象可能原因排查命令解决方案nvidia-smi 报通信失败驱动未加载lsmod | grep nvidiasudo modprobe nvidia或重启nvidia-smi 报版本不匹配驱动更新后未重启dmesg | grep -i nvidia重启系统nvcc 不是内部或外部命令PATH 未配置echo $PATH添加 CUDA bin 到 PATHPyTorch 报 libcudart 找不到CUDA 版本不匹配python -c import torch; print(torch.version.cuda)重装对应版本的 PyTorchcuDNN 版本不生效文件未复制到正确位置cat cudnn_version.h | grep MAJOR重新复制并设置权限多版本切换后 nvcc 版本不对环境变量顺序问题which nvcc调整 PATH 中 CUDA 路径的顺序WSL2 里找不到 nvidia-smi未映射 Windows 驱动ls /usr/lib/wsl/lib/添加路径到 PATH避坑技巧装 CUDA 之前先用sudo apt-mark hold把驱动和 CUDA 相关的包锁定版本防止系统自动更新导致版本错乱。这个操作在 Ubuntu 上尤其重要因为 unattended-upgrades 可能会在你不知情的情况下更新驱动。7. 版本迁移与升级从旧环境平滑过渡有时候你不是从零开始装而是要把旧环境的 CUDA 版本升级或迁移。比如从 CUDA 10.2 升到 11.8或者把一台机器上的环境复制到另一台。7.1 升级 CUDA 的正确姿势升级 CUDA 不建议直接覆盖安装而是装一个新版本然后通过环境变量切换。这样万一新版本有问题可以随时切回旧版本。步骤是先装新版本 CUDA Toolkit 到/usr/local/cuda-新版本然后装对应版本的 cuDNN最后改环境变量指向新版本。验证没问题后再考虑是否删除旧版本。7.2 环境迁移的注意事项把环境从一台机器迁移到另一台最容易出问题的是驱动版本不一致。如果目标机器的驱动版本低于源机器可能无法支持相同的 CUDA 版本。所以迁移前先确认目标机器的驱动版本必要时先升级驱动。另外Python 虚拟环境里的包不建议直接复制最好用pip freeze requirements.txt导出依赖列表在目标机器上重新安装。因为有些包在编译时会链接到特定路径的 CUDA 库直接复制可能路径对不上。8. 验证与性能测试装完不是终点装完 CUDA 和 cuDNN 之后跑一个简单的测试来验证整个链路是否通畅。8.1 用 CUDA Samples 做冒烟测试CUDA Toolkit 自带了一些示例程序在/usr/local/cuda-11.8/samples/下如果安装时勾选了 Samples。编译并运行deviceQuery这个示例cd /usr/local/cuda-11.8/samples/1_Utilities/deviceQuery sudo make ./deviceQuery如果输出里显示Result PASS说明 CUDA 环境完全正常。注意新版 CUDA Toolkit 的 runfile 安装包里可能不再包含 Samples需要单独从 GitHub 上克隆。如果找不到 samples 目录去 NVIDIA/cuda-samples 仓库下载对应版本的代码。8.2 用 PyTorch 做实际负载测试冒烟测试通过后用 PyTorch 跑一个实际的矩阵运算确认 GPU 能被框架正常调用import torch device torch.device(cuda if torch.cuda.is_available() else cpu) x torch.randn(1000, 1000).to(device) y torch.randn(1000, 1000).to(device) z torch.mm(x, y) print(z.device) print(torch.cuda.get_device_name(0))如果输出显示cuda:0和显卡型号说明整个链路——驱动、CUDA、cuDNN、PyTorch——全部打通了。我个人在实际操作中的体会是装 CUDA 环境这件事80% 的时间花在排查版本兼容性上20% 的时间才是真正的安装操作。所以与其急着敲命令不如先把版本对应关系查清楚把驱动和 Toolkit 的版本对齐后面会省很多事。另外每次改动驱动或 CUDA 版本后记得重启系统这个习惯能帮你避开至少一半的玄学报错。