WSL上的CUDA用户指南
在Windows Subsystem for Linux上使用NVIDIA CUDA的指南。
1. 在WSL 2上使用NVIDIA GPU加速计算
WSL（Windows Subsystem for Linux，即适用于Linux的Windows子系统）是Windows的一项功能，允许用户在Windows 11及更高版本操作系统上直接运行原生Linux应用程序、容器和命令行工具。本用户指南中关于CUDA的支持特指WSL 2，这是第二代WSL，具有以下优势
Linux应用程序可以在WSL 2中原样运行。WSL 2本质上是一个包含Linux WSL内核的虚拟机，提供与主流Linux内核的完全兼容性，支持包括流行Linux发行版在内的原生Linux应用程序。
更快的文件系统支持，性能更优。
WSL 2与微软Windows操作系统深度集成，这使得它能够同时运行Linux应用程序，甚至与其他Windows桌面和现代商店应用进行互操作。
在本用户指南的其余部分中，WSL和WSL 2可以互换使用。
通常，同时在Linux和Windows环境下工作的开发人员会面临非常低效的工作流程。他们不得不：
为Linux和Windows使用不同的系统，或者
双启动，即在系统的同一或不同硬盘上的独立分区中安装Linux和Windows，并选择启动到所需操作系统。
在这两种情况下，开发人员都必须停止所有工作，然后切换系统或重新启动。这也从历史上限制了两个主要生态系统之间无缝、高度集成的工具和软件系统的开发。
WSL让用户能够在两个环境之间无缝切换，无需依赖资源密集型的传统虚拟机，从而提高生产力并使用工具进行开发，整合工作流程。更重要的是，WSL 2使得原先仅在Linux上可用的应用程序现在也能在Windows上运行。WSL 2对GPU的支持让这些应用程序能够受益于GPU加速计算，并扩展了可在WSL 2上开发的应用程序领域。
借助NVIDIA CUDA对WSL 2的支持，开发者可以通过WSL在Windows上利用NVIDIA GPU加速计算技术进行数据科学、机器学习和推理任务。GPU加速还能通过减少CPU干预、在GPU上并行处理更多工作，将WSL类环境中运行应用程序的性能开销降低至接近原生环境的水平。
NVIDIA驱动程序对WSL 2的支持不仅包括CUDA，还包括DirectX和Direct ML支持。如需查看一些实用示例，请参阅https://docs.microsoft.com/en-us/windows/win32/direct3d12/gpu-tensorflow-wsl。
WSL 2是实现Windows和Linux应用程序在同一系统上无缝共享GPU加速功能的关键推动者。这提供了灵活性和多功能性，同时通过提高可访问性，进一步推动了GPU加速计算的普及。
图1. 在WSL 2上使用NVIDIA CUDA软件栈的可能性示意图
本文档描述了在WSL 2环境中开始运行CUDA应用程序或容器的工作流程。
1.1. WSL 2上的NVIDIA计算软件支持
此表记录了针对WSL 2的NVIDIA软件堆栈的准备情况及建议软件版本。
软件包 |
推荐版本 |
安装方式 |
|---|---|---|
NVIDIA Windows 驱动 x86 |
使用最新的Windows x86生产驱动。R495及更高版本的Windows将为WSL 2提供CUDA支持。 NVIDIA-SMI在WSL 2上功能有限。 传统CUDA IPC API从R510开始支持。 |
Windows x86驱动可直接从https://www.nvidia.com/Download/index.aspx下载，用于Pascal或更高版本GPU上的WSL 2支持。 |
Docker support |
Supported. NVIDIA Container Toolkit - Minimum versions - v2.6.0 with libnvidia-container - 1.5.1+ CLI and Docker Desktop Supported. |
Refer to https://docs.nvidia.com/ai-enterprise/deployment-guide-vmware/0.1.0/docker.html. |
CUDA工具包和CUDA开发者工具 |
预览版支持 计算消毒器 - Pascal及更高架构 Nsight Systems命令行工具和CUPTI（追踪） - Volta及更高架构 开发者工具 - 调试器 - Pascal及更高架构（需使用r535+版本驱动） 开发者工具 - 性能分析器 - Volta及更高架构（需在Windows 10操作系统19044+版本上使用r545+驱动，或在Windows 11上使用r525+驱动） |
最新Linux版CUDA工具包 - 12.x版本起的WSL-Ubuntu可从https://developer.nvidia.com/cuda-downloads下载。 |
RAPIDS |
22.04或更高版本 1.10 - 单GPU实验性支持。 |
|
NCCL |
2.12或更高版本 1.4+ |
2. 在WSL 2上开始使用CUDA
要开始在WSL上运行CUDA，请按顺序完成以下步骤：
2.1. 步骤1：安装NVIDIA驱动以支持GPU
在您的系统上安装NVIDIA GeForce Game Ready或NVIDIA RTX Quadro Windows 11显示驱动程序，需使用兼容的GeForce或NVIDIA RTX/Quadro显卡，下载地址为https://www.nvidia.com/Download/index.aspx。请参阅附录中的系统要求。)
注意
这是您唯一需要安装的驱动程序。不要在WSL中安装任何Linux显示驱动程序。
2.2. 步骤2：安装WSL 2
-
启动您偏好的 Windows 终端/命令提示符/Powershell 并安装 WSL：
wsl.exe --install
-
确保您已安装最新版本的WSL内核：
wsl.exe --update
2.3. 步骤3：设置Linux开发环境
从Windows终端输入WSL：
C:\> wsl.exe
默认发行版是Ubuntu。要从命令行更新为您喜欢的发行版并查看其他WSL命令，请参考以下资源：
从现在开始，您应该能够运行任何需要CUDA的现有Linux应用程序。请不要在WSL环境中安装任何驱动程序。要构建CUDA应用程序，您需要安装CUDA工具包。更多信息请阅读下一节。
3. CUDA对WSL 2的支持
最新的NVIDIA Windows GPU驱动程序将全面支持WSL 2。借助驱动程序中的CUDA支持，现有应用程序（在Linux系统上为相同目标GPU编译）可以在WSL环境中无需修改直接运行。
要编译新的CUDA应用程序，需要适用于Linux x86的CUDA工具包。CUDA工具包对WSL的支持仍处于预览阶段，因为诸如性能分析器等开发者工具尚不可用。不过，WSL2环境中完全支持CUDA应用程序开发，因此用户应能使用最新的x86 Linux版CUDA工具包来编译新的CUDA Linux应用程序。
一旦在系统上安装了Windows NVIDIA GPU驱动程序，CUDA便可在WSL 2中使用。安装在Windows主机上的CUDA驱动程序将在WSL 2中以libcuda.so的形式存根，因此用户切勿在WSL 2中安装任何NVIDIA GPU Linux驱动程序。此处需要格外注意，因为默认的CUDA工具包会附带驱动程序，很容易在默认安装过程中覆盖WSL 2的NVIDIA驱动程序。我们建议开发者使用专为WSL 2（Ubuntu）提供的独立CUDA工具包（可从CUDA Toolkit Downloads页面获取），以避免这种覆盖情况。这个WSL-Ubuntu CUDA工具包安装程序不会覆盖已映射到WSL 2环境中的NVIDIA驱动程序。要了解如何编译CUDA应用程序，请参阅Linux版的CUDA文档。
首先，移除旧的GPG密钥：
sudo apt-key del 7fa2af80
选项1：使用WSL-Ubuntu软件包安装Linux x86 CUDA工具包 - 推荐
CUDA WSL-Ubuntu本地安装包不包含NVIDIA Linux GPU驱动程序，因此按照CUDAWSL-Ubuntu下载页面上的步骤操作，您将能够在WSL上仅安装CUDA工具包。
选项2：使用元包安装Linux x86 CUDA工具包
如果您通过WSL-Ubuntu软件包安装了工具包，请跳过本节。元软件包不包含驱动程序，因此按照Ubuntu下载页面上的步骤操作，您将能够在WSL上仅安装CUDA工具包。
CUDA工具包的安装说明可在每个安装程序的CUDA工具包下载页面找到。但请勿在WSL 2下选择"cuda"、"cuda-12-x"或"cuda-drivers"元数据包，因为这些包会尝试在WSL 2下安装Linux NVIDIA驱动程序。请仅安装cuda-toolkit-12-x元数据包。
您也可以通过选择正确的元包来安装工具包的其他组件。
4. WSL 2 支持限制
WSL 2 GPU加速功能将在Pascal及更高版本的GeForce和Quadro产品SKU上以WDDM模式提供。目前尚不支持TCC模式下的Quadro GPU或Tesla GPU。
确保您使用的是最新的WSL内核版本，至少为4.19.121以上。我们推荐使用5.10.16.3或更高版本以获得更好的性能和功能修复。
如果您使用的是Windows 11系统，现在无需加入Windows预览体验计划即可使用WSL。请参阅Microsoft博客中的Windows11系统要求。
如果您仍在使用Windows 10，请参阅Windows Insider Preview和Windows 10支持。
4.1. Linux CUDA应用的已知限制
下表列出了WSL 2的已知限制，这些限制可能会影响使用某些在Linux上完全支持功能的CUDA应用程序。
限制 |
影响 |
|---|---|
不支持Maxwell GPU。 |
WSL 2官方不支持Maxwell GPU，但仍可能运行。建议使用Pascal及更高版本的GPU。 |
统一内存 - Windows原生系统不支持完整托管内存功能，因此在可预见的未来WSL 2也不会支持该功能。 |
UVM完整功能将不可用，因此依赖UVM完整功能的应用程序可能无法运行。 如果您的应用程序使用托管内存，可能会遇到性能下降和系统内存占用过高的情况。 不支持CPU/GPU并发访问。CUDA查询会显示是否支持该功能，应用程序应进行检查。 |
应用程序可用的固定系统内存（例如：应用程序为GPU访问保留的常驻系统内存）是有限的。 |
例如，某些深度学习训练工作负载，根据所使用的框架、模型和数据集大小，可能会超过此限制而无法正常工作。 |
裸金属（非容器环境）上的root用户将无法在预期位置找到nvidia-smi。 |
使用 |
对于Docker 19.03的NVIDIA容器工具包，仅支持 |
在多GPU系统中，无法通过使用特定索引编号枚举GPU来筛选特定的GPU设备。 |
4.2. 尚未支持的功能
下表列出了当前不支持的功能集。
限制 |
影响 |
|---|---|
NVML (nvidia-smi) 目前还不支持所有查询功能。 |
GPU利用率、活跃计算进程等部分查询功能尚未支持。可修改状态功能（ECC、计算模式、持久化模式）将不会得到支持。 |
尚未支持OpenGL-CUDA互操作。 |
依赖OpenGL的应用程序将无法运行。 |
5. 附录
5.1. Windows预览体验计划与Windows 10支持
如果您使用的是Windows 11，请跳过本节。Windows 11已向公众普遍开放，因此不需要特殊注册。本用户指南开头的所有说明主要针对Windows 11用户。
如果您希望在Windows 10上使用WSL 2或体验WSL 2开发的最前沿功能，可以考虑注册Windows预览体验计划并选择合适的测试通道（原快速通道），获取满足您需求的最新版本。
您可以通过运行命令输入
winver来查看您的构建版本号。
5.2. 故障排除
5.2.1. 容器运行时初始化错误
在某些情况下，运行Docker容器时，您可能会遇到nvidia-container-cli : initialization error错误：
$ sudo docker run --gpus all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark
docker: Error response from daemon: OCI runtime create failed: container_linux.go:349: starting container process caused "process_linux.go:449: container init caused \"process_linux.go:432: running prestart hook 0 caused \\\"error running hook: exit status 1, stdout: , stderr: nvidia-container-cli: initialization error: driver error: failed to process request\\\\n\\\"\"": unknown.
ERRO[0000] error waiting for container: context canceled
这通常表明正确的Windows操作系统版本或Microsoft Windows Insider预览版(仅限Windows 10)、WSL 2、NVIDIA驱动程序和NVIDIA Container Toolkit可能未正确安装。请查看已知问题和更新日志部分，确保安装了正确版本的驱动程序和容器工具包。
确保您已完成运行CUDA容器设置部分列出的所有步骤；尤其要确认docker守护进程仍在运行。
$ sudo service docker stop
$ sudo service docker start
或者直接启动守护进程，看看是否能解决问题：
$ sudo dockerd
如果仍然遇到此问题，请从运行对话框中使用dxdiag工具，并通过在开发者论坛发帖或提交报告的方式向NVIDIA提供诊断日志。
您也可以使用WSL 2上的CUDA 开发者论坛联系NVIDIA产品和工程团队获取帮助。
5.2.2. 检查WSL内核版本
-
确保您拥有最新内核，请在PowerShell中运行以下命令：
$ wsl cat /proc/version Linux version 5.10.16.3-microsoft-standard-WSL2 (x86_64-msft-linux-gcc (GCC) 9.3.0, GNU ld (GNU Binutils) 2.34.0.20200220) #1 SMP Fri Apr 2 22:23:49 UTC 2021
-
如果您没有安装最新的WSL内核，在尝试启动WSL 2容器中的Linux发行版时，将会看到以下阻止性警告：
5.3. 传统虚拟机与WSL 2对比
无论是为了高效利用硬件资源还是提升生产力，虚拟化在消费级和企业级领域都是一种更广泛应用的解决方案。虚拟化存在多种类型，深入探讨具体细节已超出本文档范围。但传统虚拟化解决方案需要安装和配置虚拟化管理软件来管理客户虚拟机。
尽管WSL 2本身是一个虚拟机，但与传统虚拟机不同，它易于设置，因为它由主机操作系统提供商提供并且非常轻量级。与传统虚拟机相比，在WSL中运行的应用程序开销更小，特别是当它们需要访问硬件或执行特权操作时，与直接在系统上运行相比。这对于GPU加速工作负载尤其重要。虽然虚拟机允许应用程序无需修改即可运行，但由于设置和性能开销的限制，在许多情况下它们并不是最佳选择。
5.4. 容器与WSL 2对比
虚拟机(VM)为应用程序提供了安全自包含的执行环境与完整的用户空间，而容器则能在避免虚拟机开销的情况下实现应用程序的组合性。容器将应用程序的所有依赖项（如库、文件等）打包在一起，便于开发以及简单可靠的部署。容器直接运行在系统安装的操作系统上，因此不像虚拟机那样提供与其他容器的完全隔离，但由此保持了可忽略不计的开销。
要了解更多关于虚拟机和容器之间的差异，请参考https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/containers-vs-vm。
6. 公告
6.1. 注意事项
本文档仅供信息参考之用，不应视为对产品功能、状态或质量的保证。NVIDIA公司（“NVIDIA”）对本文件所含信息的准确性或完整性不作任何明示或暗示的陈述或保证，并对其中可能存在的错误不承担任何责任。NVIDIA对于因使用此类信息而产生的后果、或因使用该信息导致的第三方专利或其他权利侵权概不负责。本文件不构成对开发、发布或交付任何材料（定义见下文）、代码或功能的承诺。
NVIDIA保留随时对本文件进行更正、修改、增强、改进以及任何其他变更的权利，恕不另行通知。
客户在下单前应获取最新的相关信息，并确认这些信息是最新且完整的。
除非NVIDIA与客户授权代表签署的单独销售协议中另有约定，否则NVIDIA产品的销售均以订单确认时提供的NVIDIA标准销售条款和条件为准（以下简称"销售条款"）。NVIDIA特此明确反对将任何客户通用条款适用于本文件所述NVIDIA产品的采购。本文件不直接或间接构成任何合同义务。
NVIDIA产品并非设计、授权或保证适用于医疗、军事、航空、航天或生命支持设备，也不适用于那些可以合理预期NVIDIA产品故障或失灵会导致人身伤害、死亡、财产或环境损害的应用场景。NVIDIA对于在此类设备或应用中使用和/或包含NVIDIA产品不承担任何责任，因此客户需自行承担相关风险。
NVIDIA不声明或保证基于本文档的产品适用于任何特定用途。NVIDIA未必会对每个产品的所有参数进行测试。客户应全权负责评估和确定本文档所含信息的适用性，确保产品适合并满足客户计划的应用需求，并执行必要的应用测试以避免应用或产品出现故障。客户产品设计中的缺陷可能会影响NVIDIA产品的质量和可靠性，并可能导致超出本文档范围的其他或不同的条件和/或要求。对于任何因以下原因导致的故障、损坏、成本或问题，NVIDIA不承担任何责任：(i) 以违反本文档的任何方式使用NVIDIA产品或(ii) 客户产品设计。
本文档不授予任何NVIDIA专利权、版权或其他NVIDIA知识产权的明示或暗示许可。NVIDIA发布的关于第三方产品或服务的信息，不构成NVIDIA对这些产品或服务的使用许可或担保认可。使用此类信息可能需要获得第三方基于其专利或其他知识产权的许可，或需要获得NVIDIA基于其专利或其他知识产权的许可。
本文件中的信息仅可在获得NVIDIA事先书面批准、未经改动完整复制且完全符合所有适用的出口法律法规，并附带所有相关条件、限制和声明的情况下进行复制。
本文件及所有NVIDIA设计规格、参考板、文件、图纸、诊断工具、清单和其他文档（统称及单独称为"材料"）均以"现状"提供。NVIDIA不对材料作出任何明示或默示的保证，包括但不限于对不侵权、适销性和特定用途适用性的默示保证免责。在法律允许的最大范围内，NVIDIA不就因使用本文件导致的任何损害承担责任，包括但不限于任何直接、间接、特殊、附带、惩罚性或后果性损害，无论损害成因如何，也无论责任理论为何，即使NVIDIA已被告知发生此类损害的可能性。不论客户因任何原因可能遭受的任何损害，NVIDIA对客户就本文所述产品的全部及累计责任应受产品销售条款的限制。
6.2. OpenCL
OpenCL是苹果公司的商标，经Khronos Group Inc.授权使用。
6.3. 商标
NVIDIA和NVIDIA标识是美国及其他国家NVIDIA公司的商标或注册商标。其他公司及产品名称可能是其各自关联公司的商标。