很多人在Windows上做深度学习、跑CUDA程序第一反应是装双系统或者VMware虚拟机折腾半天才发现在Windows里还有一个更轻量的选择WSL。我这次实操的就是在WSL中的Ubuntu 22.04上安装CUDA 12.8 Toolkit的完整过程包括版本选择、实操命令、环境配置还有几个踩过的坑。这篇文章适合想在Windows本机直接获得Linux编译环境、又不想重装系统的朋友参考也能帮刚接触WSL的人少走不少弯路。结合我这几天的实际安装经验先说结论在WSL2里安装CUDA Toolkit核心其实只有两步——把Windows侧的显卡驱动更新到足够新的版本然后在Linux侧装上CUDA Toolkit本体并配好环境变量。听起来简单但中间有不少细节值得展开。下面按我的实际操作顺序来记录。1. 整体设计与安装思路拆解1.1 先弄清WSL2的GPU加速原理WSL有一个很容易让人困惑的点Windows 11默认安装的WSL版本可能是WSL2也可能是旧版WSL1。只有WSL2才支持真正的GPU加速因为WSL1是通过系统调用翻译层跑Linux程序根本不包含GPU驱动支持。而WSL2则是把整个Linux内核跑在轻量级虚拟化平台上通过微软和NVIDIA联合开发的GPU-Paravirtualization技术把Windows侧显卡的计算能力直接透传给Linux侧。也就是说在WSL2里跑CUDA驱动是装在哪一侧的答案是Windows侧。NVIDIA的Windows驱动不仅服务Windows系统还内置了一个针对WSL的Linux侧驱动组件。你不需要在Ubuntu里单独安装NVIDIA显卡驱动只需要确保Windows侧的驱动版本足够新然后安装CUDA Toolkit本体就行。这也是为什么很多人第一次在WSL里输入nvidia-smi时发现能用但nvcc却提示找不到——因为nvidia-smi是通过WSL的虚拟GPU通道读取Windows驱动的信息而nvcc是CUDA Toolkit自带的编译器必须单独安装。我这次的目标很明确在Ubuntu 22.04里能用nvcc编译CUDA代码能用PyTorch调用GPU所以安装的重点是CUDA Toolkit而不是驱动。1.2 版本选型为什么锁定CUDA 12.8CUDA Toolkit版本号决定了你能用什么架构的计算能力。相较于老版本CUDA 12.8对Ada Lovelace和Hopper架构的支持更完善也修复了不少编译器和运行时的问题。我之前在Windows上用过CUDA 12.4但在PyTorch里跑某些模型时遇到过内核镜像不匹配的问题换了12.8之后问题就消失了。选版本时还要看目标框架的兼容性。如果你主要用PyTorch那么在安装前要去PyTorch官网看一眼它当前支持的CUDA版本。比如PyTorch官方有cu124、cu126、cu128这类预编译包安装前要确认好。我这次选择CUDA 12.8一方面是当前PyTorch稳定版本已经能配到cu128另一方面是后续要编译一些带自定义算子的库库作者通常也会优先适配最新一两个CUDA版本选12.8能让后面省心一点。1.3 为什么我最终选了runfile而不是debNVIDIA官网提供了两种常见的安装方式基于网络或本地deb包的安装以及runfile离线安装。在纯Ubuntu物理机上我一般推荐deb包因为它会帮你在apt层面管理依赖升级卸载都方便。但在WSL2里情况有些不同我这次最终选了runfile。原因有两个。第一deb包安装器为了避免和你已有的NVIDIA驱动冲突经常会自动执行一些和内核模块相关的操作比如检查DKMS、防止nouveau干扰等。但WSL2里根本没有传统Linux显卡驱动自然也不存在nouveau的问题deb包的那些检查反而可能报错或拖慢安装。第二runfile允许你非常精确地只安装Toolkit组件不安装驱动也方便控制安装路径这对后续多版本CUDA共存特别友好。如果你有多个项目分别依赖CUDA 11.x和12.x用runfile装到不同目录然后通过环境变量切换是更省事的路子。2. 安装前环境检查与依赖准备2.1 Windows侧检查别急着进Linux我第一次直接在WSL里敲命令结果走了不少弯路。后来发现在进入Linux之前Windows侧的准备工作比想象中更重要。首先确认Windows版本。WSL2的GPU透传需要Windows 11 21H2以上或Windows 10 21H2以上的版本。老版本系统不是不能用WSL2但GPU加速不一定能被正确识别。我当前系统是Windows 11版本号比较新这一步直接跳过。然后是驱动版本。CUDA 12.8 Toolkit要求Windows驱动版本不低于560.xx。你可以通过Windows里的“NVIDIA控制面板”查看也可以在WSL里输入nvidia-smi查看。驱动版本如果太老在WSL里就会发现nvidia-smi能输出版本信息但实际跑CUDA程序时会报CUDA driver version is insufficient。我当时是从535版升级到560版才解决所以建议你如果驱动版本较老先更新到NVIDIA官网提供的最新稳定版再继续。还有一点容易被忽略确认WSL2本身可用。在Windows PowerShell管理员模式下运行wsl --status如果显示默认版本是1要先用wsl --set-default-version 2切换到2。如果还没装WSL直接运行wsl --install这会默认安装WSL2和Ubuntu。顺便说一句WSL安装过程偶尔会很慢或卡住常见原因是未开启虚拟化或Windows服务状态异常这个我在后面的常见问题里会详细说。2.2 WSL里更新软件源和基础编译环境进入Ubuntu 22.04之后首先要做的事情是更新apt源把软件索引刷新到最新。我第一次在WSL里直接装CUDA遇到一堆依赖缺失后来发现是因为系统自带的apt源没更新很多基础包版本太旧。可以依次执行sudo apt update sudo apt upgrade -y然后安装编译CUDA程序必需的基础工具。CUDA Toolkit里带的nvcc编译时会调用系统gcc、g、make这些工具所以这些基础包必须提前装好sudo apt install -y build-essential gcc g make如果你计划用Python做深度学习顺便把Python开发工具也装上sudo apt install -y python3 python3-pip python3-venv这里有个小细节Ubuntu 22.04默认的gcc版本是11.xCUDA 12.8对gcc的支持范围到13.x所以11.x完全没问题。有些教程会让你装gcc-12甚至gcc-13这在物理机编译某些特定架构时可能有必要但在WSL2里默认gcc 11就够用了不需要额外折腾。2.3 禁用nouveauWSL里真不需要装过Linux显卡驱动的人都知道在物理机上安装NVIDIA驱动前建议先禁用开源的nouveau显卡驱动否则会冲突。但在WSL2里这一步完全不需要做。原因前面提过WSL2里本来就没有加载传统NVIDIA内核驱动模块GPU是通过Windows驱动的透传实现的和Linux本机的nouveau模块没有交集。我在操作时完全没碰nouveau相关的黑名单配置安装过程也没出任何冲突。如果你之前在物理机上装过NVIDIA驱动习惯性去找/etc/modprobe.d/blacklist-nouveau.conf在WSL里可以不用管它。话说回来虽然不需要禁用nouveau但建议确认一下WSL里是否能读到GPU信息nvidia-smi如果正常输出GPU型号和驱动版本说明Windows侧驱动透传已经生效后面装Toolkit会非常顺利。如果提示找不到nvidia-smi命令先不要继续把Windows驱动更新好、重启WSL后再试。3. 实操过程完整安装与验证3.1 下载安装包并执行安装在官网选择对应的是Linux x86_64、Ubuntu 22.04、runfile格式下载得到的就是一个.run文件。我这里下载的是cuda_12.8.0_560.28.03_linux.run这个版本。如果你后续看到小版本号略有不同比如12.8.1之类的以官网实际提供的最新文件名为准。下载可以直接用wget拉取wget https://developer.download.nvidia.com/compute/cuda/12.8.0/local_installers/cuda_12.8.0_560.28.03_linux.run如果下载速度不太理想也可以先在Windows浏览器里下载好再把文件放到WSL的家目录下访问。WSL默认会把Windows磁盘挂载到/mnt/c比如/mnt/c/Users/你的用户名/Downloads/cuda_...run直接拷贝到家目录就行。文件比较大大概4GB左右等下载完成后运行安装命令。我先给一种最省事、最安全的安静模式方案chmod x cuda_12.8.0_560.28.03_linux.run sudo sh cuda_12.8.0_560.28.03_linux.run --toolkit --silent --override --toolkit-path/usr/local/cuda-12.8解释一下这里的几个参数--toolkit只安装CUDA Toolkit不安装驱动。刚才说过WSL2里不需要Linux驱动如果强行安装反而会失败。--silent安静模式不弹出交互界面直接按默认选项安装。--override忽略安装器对gcc或环境的一些检查。如果你的系统满足要求这个参数甚至不需要加上它主要是防止某些未预期的版本检查卡住安装。--toolkit-path指定Toolkit安装路径。我指定为/usr/local/cuda-12.8方便后面多版本管理。如果你不想用安静模式想看看安装界面里有哪些可选项可以去掉--silent参数sudo sh cuda_12.8.0_560.28.03_linux.run此时会进入一个字符界面先按提示输入accept接受协议然后在组件选择界面里用方向键上下浏览把所有和Driver相关的选项都取消勾选只保留CUDA Toolkit相关的组件。这一步要小心因为默认选项可能会勾上Driver如果你没取消安装器会在WSL里尝试安装Linux驱动模块基本会报错。安装完成后检查cuda目录是否生成ls -la /usr/local/cuda*正常情况下能看到两个目录一个是具体的版本目录/usr/local/cuda-12.8另一个是软链接/usr/local/cuda指向版本目录。这个软链接非常关键很多第三方库在编译时会默认去/usr/local/cuda找你安装的CUDA以后升级版本时只需要切换软链接指向即可。3.2 配置环境变量让nvcc全局可用安装完成后环境变量不会自动生效需要手动把CUDA的bin目录和库目录加入系统的PATH和LD_LIBRARY_PATH。打开用户配置文件vim ~/.bashrc在文件末尾追加两行export PATH/usr/local/cuda-12.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH如果你希望更“通用”一点不想以后切换版本时反复改这个文件可以把路径写为/usr/local/cuda/bin和/usr/local/cuda/lib64因为/usr/local/cuda这个软链接通常一直存在切换指向就等于切换版本。不过对这个场景来说直接写死12.8版本目录也没有问题后面我讲多版本管理时再细说。保存退出后让配置立即生效source ~/.bashrc然后验证一下nvcc --version正常情况下会输出一系列Cuda compilation tools信息release 12.8V12.8.xx。到这里CUDA Toolkit的编译环境就已经装好了。3.3 验证与性能简易测试装好之后只看到一个版本号还不够我习惯写一个最小的CUDA程序真实跑一遍GPU计算确认从编译到运行整个链路都是通的。在家里建一个测试目录写一个最简单的向量加法程序。新建test.cu#include stdio.h __global__ void add(int *a, int *b, int *c) { int i threadIdx.x; c[i] a[i] b[i]; } int main() { int a[4] {1, 2, 3, 4}; int b[4] {5, 6, 7, 8}; int c[4] {0}; int *da, *db, *dc; cudaMalloc((void**)da, 4 * sizeof(int)); cudaMalloc((void**)db, 4 * sizeof(int)); cudaMalloc((void**)dc, 4 * sizeof(int)); cudaMemcpy(da, a, 4 * sizeof(int), cudaMemcpyHostToDevice); cudaMemcpy(db, b, 4 * sizeof(int), cudaMemcpyHostToDevice); add1, 4(da, db, dc); cudaMemcpy(c, dc, 4 * sizeof(int), cudaMemcpyDeviceToHost); for (int i 0; i 4; i) { printf(%d %d %d\n, a[i], b[i], c[i]); } cudaFree(da); cudaFree(db); cudaFree(dc); return 0; }然后编译运行nvcc test.cu -o test ./test如果输出结果是5、7、9、11说明编译、链接、GPU分配、内核调用这一整套流程都正常。这个程序虽然简单但已经把GPU编程的核心几个步骤都走了一遍用来做安装验证足够了。如果你装CUDA是为了PyTorch还可以在Python里快速验证一下python3 -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))如果你的PyTorch版本恰好支持CUDA 12.8输出True和显卡型号说明深度学习环境也通了。这里有一点值得提醒PyTorch的预编译包有自己的CUDA运行时依赖不是装了系统级CUDA Toolkit就能直接用任意版本。如果torch的版本匹配不对会报no kernel image is available这种错误这个我在后面常见问题里单独说。4. 常见问题排查与多版本管理4.1 明明装了但nvcc不在PATH里这个问题我见到的频率非常高。安装完成后输入nvcc --version提示command not found但去/usr/local/cuda-12.8/bin目录下看nvcc文件明明存在。这种问题的根源几乎都是环境变量没配对。一种情况是修改了~/.bashrc之后没有执行source ~/.bashrc新开的终端才会自动加载。另一种情况是你当前用的shell不是bash比如在WSL里切换到了zsh却把环境变量写到了bashrc里自然不生效。排查时可以这样which nvcc echo $PATH如果/usr/local/cuda-12.8/bin没有出现在PATH里就说明环境变量配置有问题。查看一下你当前shell是哪个echo $SHELL如果是/bin/zsh那要修改~/.zshrc而不是~/.bashrc然后把那两行export重新写一遍。如果是bash但还没生效就source ~/.bashrc。4.2 nvidia-smi正常但编译失败驱动与Toolkit的关系很多人会有个困惑明明nvidia-smi能看到驱动版本nvidia-smi显示的CUDA Version是12.8为什么nvcc还提示找不到或者编译出来的程序跑不起来这里要分清楚两组概念。nvidia-smi里显示的CUDA Version说明你的Windows驱动支持的最高CUDA运行时版本它代表的是“最高兼容能力”不是系统里已经装了CUDA Toolkit。而nvcc是Toolkit自带的编译器需要单独安装。所以看到nvidia-smi正常只代表驱动側OK不代表Toolkit也OK。反过来如果你Toolkit版本选得比驱动支持的版本还高运行程序时就会报CUDA driver version is insufficient。解决办法就是要么升级Windows侧驱动要么降低Toolkit版本。两者之间的对应关系在NVIDIA官网的驱动兼容表里写得很清楚核心原则就是保证驱动版本不低于Toolkit要求的最低版本。另外还有一种情况nvcc编译没问题但运行时提示找不到libcudart.so.12这种动态库。这种一般就是LD_LIBRARY_PATH没配对可以用ldd检查可执行文件的动态库解析情况ldd test如果有库显示not found回头检查一下~/.bashrc里的LD_LIBRARY_PATH是否包含了/usr/local/cuda-12.8/lib64然后重新source、重新编译。4.3 多版本CUDA切换的实用方案实际工程项目里经常会出现“这个项目要求CUDA 11.x那个项目要用CUDA 12.8”的情况。好在runfile方式安装的多版本CUDA天然地互不干扰因为它们安装在不同目录关键就看你怎么切换。我的做法很简单把不同版本安装到/usr/local/cuda-11.8、/usr/local/cuda-12.4、/usr/local/cuda-12.8这样的目录每个版本独立存在。然后修改/usr/local/cuda这个软链接指向当前需要的版本同时用环境变量去配合。sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda然后确保~/.bashrc里的PATH和LD_LIBRARY_PATH都指向/usr/local/cuda而不是某个特定版本目录。这样每次需要切换时只需要执行上面两条ln命令再source一下nvcc就会自动使用新版本。这里要特别注意/usr/local/cuda这个软链接必须用绝对路径创建否则有些编译器会解析错误。如果切换后nvcc --version显示的还是旧版本很可能是PATH里某个目录把旧版本的bin放在更前面。可以用type nvcc确认一下nvcc实际是从哪个目录加载的。4.4 WSL安装太慢、启动异常与目录迁移最后再整理几个WSL本身的常见状况。先说你很可能遇到的执行wsl --install后长时间卡在“正在安装”这个界面进度好像不动。这个不一定是卡死有时候只是网络慢。可以先在PowerShell里运行wsl --update让WSL组件更新到最新版再重启终端重试。如果还是卡检查电脑是否开启了虚拟化功能重启后进BIOS确认Intel VT-x或AMD SVM是开启状态。虚拟化没启用的话WSL2根本起不来。还有一种情况是启动WSL时报错提示服务无法启动原因可能是被禁用或没有启动相关设备。这个通常在Windows服务里把和WSL相关的服务运行起来就行。打开“服务”窗口找到名类似LxssManager的服务把它启动类型设为自动然后启动服务再试一次wsl。最后一个典型问题是磁盘空间。WSL的虚拟磁盘文件默认放在C盘用户目录下随着你安装CUDA、Python包、模型文件虚拟磁盘会飞速膨胀。C盘不够时操作会变得很卡甚至直接报错。我的建议是如果C盘空间紧张趁早迁移WSL发行版。迁移步骤不复杂在Windows侧操作wsl --shutdown wsl --export Ubuntu D:\wsl-ubuntu-backup.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\wsl\Ubuntu D:\wsl-ubuntu-backup.tar --version 2注意unregister会删除原发行版里的所有数据所以export备份那一步一定不能漏。迁移完成后WSL会从新的路径加载磁盘镜像。这个方法不仅能救急也可以作为给C盘“瘦身”的常规手段。回到CUDA安装本身我最后再提醒一点完成全部配置后最好把版本信息记录到一个固定文件里比如写一个setup-notes.md记下CUDA版本、驱动版本、PyTorch版本和安装日期。虽然现在看起来多此一举但三个月后你需要在同一台机器上重建环境时这份记录能帮你省下大量排查时间。我这次就是在笔记本上记录了安装命令和遇到的两个坑后面帮同事部署时照着走一遍十分钟就完事。安装这类基础工具链最怕的不是步骤复杂而是不同教程混杂在一起让人无所适从。按我上面这条路子走基本能一次通过。 WSL2上安装CUDA 12.8完整指南：深度学习GPU环境配置
很多人在Windows上做深度学习、跑CUDA程序第一反应是装双系统或者VMware虚拟机折腾半天才发现在Windows里还有一个更轻量的选择WSL。我这次实操的就是在WSL中的Ubuntu 22.04上安装CUDA 12.8 Toolkit的完整过程包括版本选择、实操命令、环境配置还有几个踩过的坑。这篇文章适合想在Windows本机直接获得Linux编译环境、又不想重装系统的朋友参考也能帮刚接触WSL的人少走不少弯路。结合我这几天的实际安装经验先说结论在WSL2里安装CUDA Toolkit核心其实只有两步——把Windows侧的显卡驱动更新到足够新的版本然后在Linux侧装上CUDA Toolkit本体并配好环境变量。听起来简单但中间有不少细节值得展开。下面按我的实际操作顺序来记录。1. 整体设计与安装思路拆解1.1 先弄清WSL2的GPU加速原理WSL有一个很容易让人困惑的点Windows 11默认安装的WSL版本可能是WSL2也可能是旧版WSL1。只有WSL2才支持真正的GPU加速因为WSL1是通过系统调用翻译层跑Linux程序根本不包含GPU驱动支持。而WSL2则是把整个Linux内核跑在轻量级虚拟化平台上通过微软和NVIDIA联合开发的GPU-Paravirtualization技术把Windows侧显卡的计算能力直接透传给Linux侧。也就是说在WSL2里跑CUDA驱动是装在哪一侧的答案是Windows侧。NVIDIA的Windows驱动不仅服务Windows系统还内置了一个针对WSL的Linux侧驱动组件。你不需要在Ubuntu里单独安装NVIDIA显卡驱动只需要确保Windows侧的驱动版本足够新然后安装CUDA Toolkit本体就行。这也是为什么很多人第一次在WSL里输入nvidia-smi时发现能用但nvcc却提示找不到——因为nvidia-smi是通过WSL的虚拟GPU通道读取Windows驱动的信息而nvcc是CUDA Toolkit自带的编译器必须单独安装。我这次的目标很明确在Ubuntu 22.04里能用nvcc编译CUDA代码能用PyTorch调用GPU所以安装的重点是CUDA Toolkit而不是驱动。1.2 版本选型为什么锁定CUDA 12.8CUDA Toolkit版本号决定了你能用什么架构的计算能力。相较于老版本CUDA 12.8对Ada Lovelace和Hopper架构的支持更完善也修复了不少编译器和运行时的问题。我之前在Windows上用过CUDA 12.4但在PyTorch里跑某些模型时遇到过内核镜像不匹配的问题换了12.8之后问题就消失了。选版本时还要看目标框架的兼容性。如果你主要用PyTorch那么在安装前要去PyTorch官网看一眼它当前支持的CUDA版本。比如PyTorch官方有cu124、cu126、cu128这类预编译包安装前要确认好。我这次选择CUDA 12.8一方面是当前PyTorch稳定版本已经能配到cu128另一方面是后续要编译一些带自定义算子的库库作者通常也会优先适配最新一两个CUDA版本选12.8能让后面省心一点。1.3 为什么我最终选了runfile而不是debNVIDIA官网提供了两种常见的安装方式基于网络或本地deb包的安装以及runfile离线安装。在纯Ubuntu物理机上我一般推荐deb包因为它会帮你在apt层面管理依赖升级卸载都方便。但在WSL2里情况有些不同我这次最终选了runfile。原因有两个。第一deb包安装器为了避免和你已有的NVIDIA驱动冲突经常会自动执行一些和内核模块相关的操作比如检查DKMS、防止nouveau干扰等。但WSL2里根本没有传统Linux显卡驱动自然也不存在nouveau的问题deb包的那些检查反而可能报错或拖慢安装。第二runfile允许你非常精确地只安装Toolkit组件不安装驱动也方便控制安装路径这对后续多版本CUDA共存特别友好。如果你有多个项目分别依赖CUDA 11.x和12.x用runfile装到不同目录然后通过环境变量切换是更省事的路子。2. 安装前环境检查与依赖准备2.1 Windows侧检查别急着进Linux我第一次直接在WSL里敲命令结果走了不少弯路。后来发现在进入Linux之前Windows侧的准备工作比想象中更重要。首先确认Windows版本。WSL2的GPU透传需要Windows 11 21H2以上或Windows 10 21H2以上的版本。老版本系统不是不能用WSL2但GPU加速不一定能被正确识别。我当前系统是Windows 11版本号比较新这一步直接跳过。然后是驱动版本。CUDA 12.8 Toolkit要求Windows驱动版本不低于560.xx。你可以通过Windows里的“NVIDIA控制面板”查看也可以在WSL里输入nvidia-smi查看。驱动版本如果太老在WSL里就会发现nvidia-smi能输出版本信息但实际跑CUDA程序时会报CUDA driver version is insufficient。我当时是从535版升级到560版才解决所以建议你如果驱动版本较老先更新到NVIDIA官网提供的最新稳定版再继续。还有一点容易被忽略确认WSL2本身可用。在Windows PowerShell管理员模式下运行wsl --status如果显示默认版本是1要先用wsl --set-default-version 2切换到2。如果还没装WSL直接运行wsl --install这会默认安装WSL2和Ubuntu。顺便说一句WSL安装过程偶尔会很慢或卡住常见原因是未开启虚拟化或Windows服务状态异常这个我在后面的常见问题里会详细说。2.2 WSL里更新软件源和基础编译环境进入Ubuntu 22.04之后首先要做的事情是更新apt源把软件索引刷新到最新。我第一次在WSL里直接装CUDA遇到一堆依赖缺失后来发现是因为系统自带的apt源没更新很多基础包版本太旧。可以依次执行sudo apt update sudo apt upgrade -y然后安装编译CUDA程序必需的基础工具。CUDA Toolkit里带的nvcc编译时会调用系统gcc、g、make这些工具所以这些基础包必须提前装好sudo apt install -y build-essential gcc g make如果你计划用Python做深度学习顺便把Python开发工具也装上sudo apt install -y python3 python3-pip python3-venv这里有个小细节Ubuntu 22.04默认的gcc版本是11.xCUDA 12.8对gcc的支持范围到13.x所以11.x完全没问题。有些教程会让你装gcc-12甚至gcc-13这在物理机编译某些特定架构时可能有必要但在WSL2里默认gcc 11就够用了不需要额外折腾。2.3 禁用nouveauWSL里真不需要装过Linux显卡驱动的人都知道在物理机上安装NVIDIA驱动前建议先禁用开源的nouveau显卡驱动否则会冲突。但在WSL2里这一步完全不需要做。原因前面提过WSL2里本来就没有加载传统NVIDIA内核驱动模块GPU是通过Windows驱动的透传实现的和Linux本机的nouveau模块没有交集。我在操作时完全没碰nouveau相关的黑名单配置安装过程也没出任何冲突。如果你之前在物理机上装过NVIDIA驱动习惯性去找/etc/modprobe.d/blacklist-nouveau.conf在WSL里可以不用管它。话说回来虽然不需要禁用nouveau但建议确认一下WSL里是否能读到GPU信息nvidia-smi如果正常输出GPU型号和驱动版本说明Windows侧驱动透传已经生效后面装Toolkit会非常顺利。如果提示找不到nvidia-smi命令先不要继续把Windows驱动更新好、重启WSL后再试。3. 实操过程完整安装与验证3.1 下载安装包并执行安装在官网选择对应的是Linux x86_64、Ubuntu 22.04、runfile格式下载得到的就是一个.run文件。我这里下载的是cuda_12.8.0_560.28.03_linux.run这个版本。如果你后续看到小版本号略有不同比如12.8.1之类的以官网实际提供的最新文件名为准。下载可以直接用wget拉取wget https://developer.download.nvidia.com/compute/cuda/12.8.0/local_installers/cuda_12.8.0_560.28.03_linux.run如果下载速度不太理想也可以先在Windows浏览器里下载好再把文件放到WSL的家目录下访问。WSL默认会把Windows磁盘挂载到/mnt/c比如/mnt/c/Users/你的用户名/Downloads/cuda_...run直接拷贝到家目录就行。文件比较大大概4GB左右等下载完成后运行安装命令。我先给一种最省事、最安全的安静模式方案chmod x cuda_12.8.0_560.28.03_linux.run sudo sh cuda_12.8.0_560.28.03_linux.run --toolkit --silent --override --toolkit-path/usr/local/cuda-12.8解释一下这里的几个参数--toolkit只安装CUDA Toolkit不安装驱动。刚才说过WSL2里不需要Linux驱动如果强行安装反而会失败。--silent安静模式不弹出交互界面直接按默认选项安装。--override忽略安装器对gcc或环境的一些检查。如果你的系统满足要求这个参数甚至不需要加上它主要是防止某些未预期的版本检查卡住安装。--toolkit-path指定Toolkit安装路径。我指定为/usr/local/cuda-12.8方便后面多版本管理。如果你不想用安静模式想看看安装界面里有哪些可选项可以去掉--silent参数sudo sh cuda_12.8.0_560.28.03_linux.run此时会进入一个字符界面先按提示输入accept接受协议然后在组件选择界面里用方向键上下浏览把所有和Driver相关的选项都取消勾选只保留CUDA Toolkit相关的组件。这一步要小心因为默认选项可能会勾上Driver如果你没取消安装器会在WSL里尝试安装Linux驱动模块基本会报错。安装完成后检查cuda目录是否生成ls -la /usr/local/cuda*正常情况下能看到两个目录一个是具体的版本目录/usr/local/cuda-12.8另一个是软链接/usr/local/cuda指向版本目录。这个软链接非常关键很多第三方库在编译时会默认去/usr/local/cuda找你安装的CUDA以后升级版本时只需要切换软链接指向即可。3.2 配置环境变量让nvcc全局可用安装完成后环境变量不会自动生效需要手动把CUDA的bin目录和库目录加入系统的PATH和LD_LIBRARY_PATH。打开用户配置文件vim ~/.bashrc在文件末尾追加两行export PATH/usr/local/cuda-12.8/bin:$PATH export LD_LIBRARY_PATH/usr/local/cuda-12.8/lib64:$LD_LIBRARY_PATH如果你希望更“通用”一点不想以后切换版本时反复改这个文件可以把路径写为/usr/local/cuda/bin和/usr/local/cuda/lib64因为/usr/local/cuda这个软链接通常一直存在切换指向就等于切换版本。不过对这个场景来说直接写死12.8版本目录也没有问题后面我讲多版本管理时再细说。保存退出后让配置立即生效source ~/.bashrc然后验证一下nvcc --version正常情况下会输出一系列Cuda compilation tools信息release 12.8V12.8.xx。到这里CUDA Toolkit的编译环境就已经装好了。3.3 验证与性能简易测试装好之后只看到一个版本号还不够我习惯写一个最小的CUDA程序真实跑一遍GPU计算确认从编译到运行整个链路都是通的。在家里建一个测试目录写一个最简单的向量加法程序。新建test.cu#include stdio.h __global__ void add(int *a, int *b, int *c) { int i threadIdx.x; c[i] a[i] b[i]; } int main() { int a[4] {1, 2, 3, 4}; int b[4] {5, 6, 7, 8}; int c[4] {0}; int *da, *db, *dc; cudaMalloc((void**)da, 4 * sizeof(int)); cudaMalloc((void**)db, 4 * sizeof(int)); cudaMalloc((void**)dc, 4 * sizeof(int)); cudaMemcpy(da, a, 4 * sizeof(int), cudaMemcpyHostToDevice); cudaMemcpy(db, b, 4 * sizeof(int), cudaMemcpyHostToDevice); add1, 4(da, db, dc); cudaMemcpy(c, dc, 4 * sizeof(int), cudaMemcpyDeviceToHost); for (int i 0; i 4; i) { printf(%d %d %d\n, a[i], b[i], c[i]); } cudaFree(da); cudaFree(db); cudaFree(dc); return 0; }然后编译运行nvcc test.cu -o test ./test如果输出结果是5、7、9、11说明编译、链接、GPU分配、内核调用这一整套流程都正常。这个程序虽然简单但已经把GPU编程的核心几个步骤都走了一遍用来做安装验证足够了。如果你装CUDA是为了PyTorch还可以在Python里快速验证一下python3 -c import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))如果你的PyTorch版本恰好支持CUDA 12.8输出True和显卡型号说明深度学习环境也通了。这里有一点值得提醒PyTorch的预编译包有自己的CUDA运行时依赖不是装了系统级CUDA Toolkit就能直接用任意版本。如果torch的版本匹配不对会报no kernel image is available这种错误这个我在后面常见问题里单独说。4. 常见问题排查与多版本管理4.1 明明装了但nvcc不在PATH里这个问题我见到的频率非常高。安装完成后输入nvcc --version提示command not found但去/usr/local/cuda-12.8/bin目录下看nvcc文件明明存在。这种问题的根源几乎都是环境变量没配对。一种情况是修改了~/.bashrc之后没有执行source ~/.bashrc新开的终端才会自动加载。另一种情况是你当前用的shell不是bash比如在WSL里切换到了zsh却把环境变量写到了bashrc里自然不生效。排查时可以这样which nvcc echo $PATH如果/usr/local/cuda-12.8/bin没有出现在PATH里就说明环境变量配置有问题。查看一下你当前shell是哪个echo $SHELL如果是/bin/zsh那要修改~/.zshrc而不是~/.bashrc然后把那两行export重新写一遍。如果是bash但还没生效就source ~/.bashrc。4.2 nvidia-smi正常但编译失败驱动与Toolkit的关系很多人会有个困惑明明nvidia-smi能看到驱动版本nvidia-smi显示的CUDA Version是12.8为什么nvcc还提示找不到或者编译出来的程序跑不起来这里要分清楚两组概念。nvidia-smi里显示的CUDA Version说明你的Windows驱动支持的最高CUDA运行时版本它代表的是“最高兼容能力”不是系统里已经装了CUDA Toolkit。而nvcc是Toolkit自带的编译器需要单独安装。所以看到nvidia-smi正常只代表驱动側OK不代表Toolkit也OK。反过来如果你Toolkit版本选得比驱动支持的版本还高运行程序时就会报CUDA driver version is insufficient。解决办法就是要么升级Windows侧驱动要么降低Toolkit版本。两者之间的对应关系在NVIDIA官网的驱动兼容表里写得很清楚核心原则就是保证驱动版本不低于Toolkit要求的最低版本。另外还有一种情况nvcc编译没问题但运行时提示找不到libcudart.so.12这种动态库。这种一般就是LD_LIBRARY_PATH没配对可以用ldd检查可执行文件的动态库解析情况ldd test如果有库显示not found回头检查一下~/.bashrc里的LD_LIBRARY_PATH是否包含了/usr/local/cuda-12.8/lib64然后重新source、重新编译。4.3 多版本CUDA切换的实用方案实际工程项目里经常会出现“这个项目要求CUDA 11.x那个项目要用CUDA 12.8”的情况。好在runfile方式安装的多版本CUDA天然地互不干扰因为它们安装在不同目录关键就看你怎么切换。我的做法很简单把不同版本安装到/usr/local/cuda-11.8、/usr/local/cuda-12.4、/usr/local/cuda-12.8这样的目录每个版本独立存在。然后修改/usr/local/cuda这个软链接指向当前需要的版本同时用环境变量去配合。sudo rm /usr/local/cuda sudo ln -s /usr/local/cuda-12.8 /usr/local/cuda然后确保~/.bashrc里的PATH和LD_LIBRARY_PATH都指向/usr/local/cuda而不是某个特定版本目录。这样每次需要切换时只需要执行上面两条ln命令再source一下nvcc就会自动使用新版本。这里要特别注意/usr/local/cuda这个软链接必须用绝对路径创建否则有些编译器会解析错误。如果切换后nvcc --version显示的还是旧版本很可能是PATH里某个目录把旧版本的bin放在更前面。可以用type nvcc确认一下nvcc实际是从哪个目录加载的。4.4 WSL安装太慢、启动异常与目录迁移最后再整理几个WSL本身的常见状况。先说你很可能遇到的执行wsl --install后长时间卡在“正在安装”这个界面进度好像不动。这个不一定是卡死有时候只是网络慢。可以先在PowerShell里运行wsl --update让WSL组件更新到最新版再重启终端重试。如果还是卡检查电脑是否开启了虚拟化功能重启后进BIOS确认Intel VT-x或AMD SVM是开启状态。虚拟化没启用的话WSL2根本起不来。还有一种情况是启动WSL时报错提示服务无法启动原因可能是被禁用或没有启动相关设备。这个通常在Windows服务里把和WSL相关的服务运行起来就行。打开“服务”窗口找到名类似LxssManager的服务把它启动类型设为自动然后启动服务再试一次wsl。最后一个典型问题是磁盘空间。WSL的虚拟磁盘文件默认放在C盘用户目录下随着你安装CUDA、Python包、模型文件虚拟磁盘会飞速膨胀。C盘不够时操作会变得很卡甚至直接报错。我的建议是如果C盘空间紧张趁早迁移WSL发行版。迁移步骤不复杂在Windows侧操作wsl --shutdown wsl --export Ubuntu D:\wsl-ubuntu-backup.tar wsl --unregister Ubuntu wsl --import Ubuntu D:\wsl\Ubuntu D:\wsl-ubuntu-backup.tar --version 2注意unregister会删除原发行版里的所有数据所以export备份那一步一定不能漏。迁移完成后WSL会从新的路径加载磁盘镜像。这个方法不仅能救急也可以作为给C盘“瘦身”的常规手段。回到CUDA安装本身我最后再提醒一点完成全部配置后最好把版本信息记录到一个固定文件里比如写一个setup-notes.md记下CUDA版本、驱动版本、PyTorch版本和安装日期。虽然现在看起来多此一举但三个月后你需要在同一台机器上重建环境时这份记录能帮你省下大量排查时间。我这次就是在笔记本上记录了安装命令和遇到的两个坑后面帮同事部署时照着走一遍十分钟就完事。安装这类基础工具链最怕的不是步骤复杂而是不同教程混杂在一起让人无所适从。按我上面这条路子走基本能一次通过。