CUDA on WSL 用户指南

在 Windows Subsystem for Linux 上使用 NVIDIA CUDA 的指南。

1. 在 WSL 2 上使用 NVIDIA GPU 加速计算

WSL 或 Windows Subsystem for Linux 是一个 Windows 功能，使用户能够直接在 Windows 11 及更高版本的操作系统版本上运行原生 Linux 应用程序、容器和命令行工具。本用户指南中的 CUDA 支持专门针对 WSL 2，它是 WSL 的第二代，具有以下优势

  • Linux 应用程序可以在 WSL 2 中按原样运行。WSL 2 本质上是一个虚拟机，其中包含 Linux WSL 内核，它提供与主流 Linux 内核的完全兼容性，从而支持原生 Linux 应用程序，包括流行的 Linux 发行版。

  • 更快的文件系统支持，并且性能更高。

  • WSL 2 与 Microsoft Windows 操作系统紧密集成，这使其能够与其他 Windows 桌面和现代商店应用并行运行 Linux 应用程序，甚至可以与它们进行互操作。

在本用户指南的其余部分，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 加速还有助于降低在 WSL 等环境中运行应用程序的性能开销，使其接近原生性能，因为它能够通过更少的 CPU 干预在 GPU 上流水线处理更多并行工作。

NVIDIA 对 WSL 2 的驱动程序支持不仅包括 CUDA，还包括 DirectX 和 Direct ML 支持。有关一些有用的示例，请参阅 https://docs.microsoft.com/en-us/windows/win32/direct3d12/gpu-tensorflow-wsl。

WSL 2 是使 GPU 加速能够在同一系统上的 Windows 和 Linux 应用程序之间无缝共享成为现实的关键推动因素。这提供了灵活性和多功能性，同时也有助于通过使其更易于访问来开放 GPU 加速计算。

Illustration of the possibilities with NVIDIA CUDA software stack on WSL 2

图 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 上将具有有限的功能集。

R510 及更高版本支持旧版 CUDA IPC API。

Windows x86 驱动程序可以直接从 https://www.nvidia.com/Download/index.aspx 下载，以在 Pascal 或更高版本的 GPU 上获得 WSL 2 支持。

Docker 支持

受支持。

NVIDIA Container Toolkit - 最低版本 - v2.6.0，libnvidia-container - 1.5.1+

支持 CLI 和 Docker Desktop。

请参阅 https://docs.nvda.net.cn/ai-enterprise/deployment-guide-vmware/0.1.0/docker.html。

CUDA 工具包和 CUDA 开发人员工具

预览支持

Compute Sanitizer - Pascal 及更高版本

Nsight Systems CLI 和 CUPTI（跟踪）- Volta 及更高版本

开发人员工具 - 调试器 - Pascal 及更高版本（使用驱动程序 r535+）

开发人员工具 - 分析器 - Volta 及更高版本（使用 Windows 10 操作系统版本 19044+ 和驱动程序 r545+，或使用 Windows 11 和驱动程序 r525+）

最新的 Linux CUDA 工具包软件包 - 可以从 https://developer.nvidia.com/cuda-downloads 下载 12.x 发行版中的 WSL-Ubuntu。

RAPIDS

22.04 或更高版本 1.10 - 单 GPU 的实验性支持。

https://docs.rapids.ai/notices/rgn0024/

NCCL

2.12 或更高版本 1.4+

请参阅 Linux x86 的 NCCL 安装指南。

2. CUDA on WSL 2 入门

要开始在 WSL 上运行 CUDA，请按顺序完成以下步骤

2.1. 步骤 1：安装 NVIDIA 驱动程序以获得 GPU 支持

  • 在您的系统上安装 NVIDIA GeForce Game Ready 或 NVIDIA RTX Quadro Windows 11 显示驱动程序，该系统具有来自 https://www.nvidia.com/Download/index.aspx 的兼容 GeForce 或 NVIDIA RTX/Quadro 卡。（请参阅附录中的系统要求。）

注意

这是您唯一需要安装的驱动程序。请勿在 WSL 中安装任何 Linux 显示驱动程序。

2.2. 步骤 2：安装 WSL 2

  1. 启动您首选的 Windows 终端/命令提示符/Powershell 并安装 WSL

    wsl.exe --install

  2. 确保您拥有最新的 WSL 内核

    wsl.exe --update

2.3. 步骤 3：设置 Linux 开发环境

从 Windows 终端，输入 WSL

C:\> wsl.exe

默认发行版是 Ubuntu。要从命令行将发行版更新为您喜欢的发行版，并查看其他 WSL 命令，请参阅以下资源

从现在开始，您应该能够运行任何需要 CUDA 的现有 Linux 应用程序。请勿在 WSL 环境中安装任何驱动程序。要构建 CUDA 应用程序，您将需要 CUDA 工具包。请阅读下一节以获取更多信息。

3. WSL 2 的 CUDA 支持

最新的 NVIDIA Windows GPU 驱动程序将完全支持 WSL 2。借助驱动程序中的 CUDA 支持，现有应用程序（在 Linux 系统上为相同的目标 GPU 编译）可以在 WSL 环境中未经修改地运行。

要编译新的 CUDA 应用程序，需要 Linux x86 的 CUDA 工具包。WSL 的 CUDA 工具包支持仍处于预览阶段，因为分析器等开发人员工具尚不可用。但是，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 驱动程序。我们建议开发人员使用单独的 CUDA 工具包用于 WSL 2（Ubuntu），可从 CUDA 工具包下载 页面获取，以避免此覆盖。此 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 驱动程序，因此通过按照 CUDA WSL-Ubuntu 下载页面上的步骤操作，您将能够仅在 WSL 上安装 CUDA 工具包。

选项 2：使用 Meta 软件包安装 Linux x86 CUDA 工具包

如果您使用 WSL-Ubuntu 软件包安装了工具包，请跳过本节。Meta 软件包不包含驱动程序，因此通过按照 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 加速将在 WDDM 模式下的 GeForce 和 Quadro 产品 SKU 上的 Pascal 及更高版本的 GPU 架构上可用。它在 TCC 模式下的 Quadro GPU 或 Tesla GPU 上尚不可用。

  • 确保您使用的是最新的 WSL 内核或至少 4.19.121+。我们建议使用 5.10.16.3 或更高版本以获得更好的性能和功能修复。

  • 如果您使用的是 Windows 11，则不再需要加入 Windows 预览体验计划即可使用 WSL。请参阅 Microsoft 博客中的 Windows 11 系统要求。

  • 如果您继续使用 Windows 10，请参阅 Windows 预览体验计划和 Windows 10 支持。

4.1. Linux CUDA 应用程序的已知限制

下表列出了 WSL 2 上可能影响 CUDA 应用程序的已知限制，这些应用程序使用在 Linux 上完全支持的某些功能。

限制

影响

不支持 Maxwell GPU。

WSL 2 中未正式支持 Maxwell GPU，但它可能仍然可以工作。建议使用 Pascal 及更高版本的 GPU。

统一内存 - Windows 原生不支持完全托管内存支持，因此 WSL 2 在可预见的未来将不支持它。

UVM 的全部功能将不可用，因此依赖 UVM 全部功能的应用程序可能无法工作。

如果您的应用程序正在使用托管内存，则您的应用程序可能会看到性能下降和系统内存使用率过高。

不支持并发 CPU/GPU 访问。CUDA 查询将说明是否支持它，并且应用程序应检查这一点。

应用程序可用的固定系统内存（例如：应用程序为 GPU 访问保留的系统内存）受到限制。

例如，某些深度学习训练工作负载，具体取决于使用的框架、模型和数据集大小，可能会超出此限制，并且可能无法工作。

裸机（非容器）上的 root 用户将无法在预期位置找到 nvidia-smi。

使用 /usr/lib/wsl/lib/nvidia-smi 或手动将 /usr/lib/wsl/lib/ 添加到 PATH）。

对于 Docker 19.03 的 NVIDIA Container Toolkit，仅支持 --gpus all。

在多 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 预览体验计划 并选择适当的 预览体验通道（以前的快速通道），并获得满足您需求的最新版本。

  • 了解更多信息，请访问 发布 Windows 10 Build 19043.1263 (21H1) 到发布预览通道。

  • 您可以通过运行 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 预览体验计划版本（仅限 Windows 10）、WSL 2、NVIDIA 驱动程序和 NVIDIA Container Toolkit。查看已知问题和变更日志部分，以确保安装了正确版本的驱动程序和容器工具包。

确保您已完成 CUDA 容器运行下的设置下列出的步骤；尤其要确保 docker 守护程序仍在运行。

$ sudo service docker stop
$ sudo service docker start

或者直接启动守护程序，看看是否可以解决问题

$ sudo dockerd

如果您仍然遇到此问题，请使用“运行”对话框中的 dxdiag 工具，并通过在 开发者论坛 中发布或提交 报告，将诊断日志提供给 NVIDIA。

您还可以使用 CUDA on WSL 2 开发者论坛 与 NVIDIA 产品和工程团队联系以获得帮助。

5.2.2. 检查 WSL 内核版本

  1. 通过在 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

  2. 如果您没有最新的 WSL 内核，您将在尝试在 WSL 2 容器中启动 Linux 发行版时看到以下阻止警告

    _images/wsl2-ubuntu-lts.png

5.3. 传统虚拟机与 WSL 2

无论是为了有效利用硬件资源还是提高生产力，虚拟化都是消费者和企业领域中更广泛使用的解决方案。虚拟化有不同的类型，深入研究其细节超出了本文档的范围。但是，传统的虚拟化解决方案需要安装和设置虚拟化管理软件来管理来宾虚拟机。

虽然 WSL 2 本身就是一个虚拟机，但与传统虚拟机不同，它易于设置，因为它由主机操作系统提供商提供，并且非常轻量级。与传统虚拟机相比，在 WSL 中运行的应用程序的开销更少，特别是当它们需要访问硬件或执行特权操作时，与直接在系统上运行时相比更是如此。这对于 GPU 加速工作负载尤其重要。虽然虚拟机允许应用程序未经修改地运行，但由于设置和性能开销的限制，它们在许多情况下不是最佳选择。

5.4. 容器与 WSL 2

虽然虚拟机为应用程序提供了安全的自包含执行环境，并具有完整的用户空间，但容器实现了应用程序的可组合性，而没有虚拟机的开销。容器组合了应用程序的所有依赖项，例如库、文件等，以便捆绑在一起进行开发和轻松且可预测的部署。容器直接在系统上安装的操作系统上运行，因此不提供像虚拟机那样的与其他容器的完全隔离，但结果是开销可以忽略不计。

要了解有关虚拟机和容器之间差异的更多信息，请参阅 https://docs.microsoft.com/en-us/virtualization/windowscontainers/about/containers-vs-vm。

6. 通知

6.1. 通知

本文档仅供参考，不应视为对产品的特定功能、条件或质量的保证。NVIDIA Corporation（“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 已被告知可能发生此类损害。尽管客户可能因任何原因而遭受任何损害，但 NVIDIA 对本文所述产品的客户承担的累计责任应根据产品的销售条款进行限制。

6.2. OpenCL

OpenCL 是 Apple Inc. 的商标，已获得 Khronos Group Inc. 的许可使用。

6.3. 商标

NVIDIA 和 NVIDIA 徽标是 NVIDIA Corporation 在美国和其他国家/地区的商标或注册商标。其他公司和产品名称可能是与其关联的各个公司的商标。