返回
创建于
状态公开

Windows 下 Docker Desktop 启用 CUDA 全攻略（含完整排查流程）

在 Windows 上使用 Docker Desktop 跑 GPU（CUDA）容器，是许多深度学习开发者与 AI 工程师的常见需求。但 Windows 本身并不能直接给 Docker 传递 GPU，真正可行的方案是：

WSL2 + NVIDIA 驱动（支持 WSL CUDA）+ Docker Desktop（WSL backend）+ NVIDIA Container Toolkit

本文提供从安装、配置到排查全部问题的完整指南，让你的 GPU 能稳定可用。

目录

  1. 为什么必须通过 WSL2 才能使用 GPU\
  2. 环境要求\
  3. 安装步骤\
  4. 测试 CUDA 是否可用\
  5. 常见问题排查\
  6. 总结\
  7. 一键排查 Checklist

1. 为什么 Docker Desktop 必须通过 WSL2 才能使用 GPU？

Docker Desktop 运行容器的方式有两种：

  • Windows 容器（不支持 GPU）
  • Linux 容器（仅在 WSL2 模式 才能访问 GPU）

要让容器看到显卡，必须走下面这条链路：

js
1Windows → NVIDIA 驱动（支持 WSL） → WSL2 → Docker Desktop → Linux 容器 → GPU

2. 环境要求

  • Windows 10 / 11（需要支持 WSL2）
  • NVIDIA GPU（RTX / GTX / Quadro / Tesla 等）
  • NVIDIA 驱动 470+（支持 WSL2 CUDA）
  • Docker Desktop（启用 WSL2 backend）
  • WSL2 Linux 发行版（Ubuntu 推荐）

3. 安装 & 配置步骤

第一步：让 Docker Desktop 使用 WSL2

Docker Desktop → Settings → General：

✔ Enable the WSL 2 based engine

Settings → Resources → WSL Integration：

✔ 启用 Ubuntu（或你使用的发行版）

第二步：安装支持 WSL2 的 NVIDIA 驱动

安装官方 NVIDIA 驱动（470+），并测试：

powershell
1nvidia-smi

第三步：在 WSL2 内安装 NVIDIA Container Toolkit

bash
1curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey   | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
2
3curl -s -L https://nvidia.github.io/libnvidia-container/stable/list.deb   | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g'   | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
4
5sudo apt update
6sudo apt install -y nvidia-container-toolkit
7
8sudo nvidia-ctk runtime configure --runtime=docker
9sudo systemctl restart docker

4. 测试 CUDA 是否可用

bash
1docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

5. 常见问题排查

1. 发行版不是 WSL2

powershell
1wsl -l -v

如不是 version 2：

powershell
1wsl --set-version <发行版> 2

2. WSL 未检测到 GPU

powershell
1wsl --status

显示必须为：

js
1GPU: NVIDIA

3. Hyper-V / VMware 冲突导致 GPU 不可用

powershell
1DISM /Online /Get-Features /format:table | findstr Hyper-V

如启用可关闭：

powershell
1DISM /Online /Disable-Feature /FeatureName:Microsoft-Hyper-V-All

4. WSL 过旧

powershell
1wsl --update
2wsl --shutdown

5. 进入了错误的环境

避免：

js
1docker-desktop:~# nvidia-smi

正确方式：

bash
1wsl -d Ubuntu
2nvidia-smi

6. 总结

启用 GPU 的关键：

  • WSL2\
  • WSL2 CUDA 驱动\
  • NVIDIA Container Toolkit\
  • Docker Desktop WSL backend\
  • Linux Containers

验证命令：

bash
1docker run --rm --gpus all nvidia/cuda nvidia-smi

7. 一键排查 Checklist

Windows

  • nvidia-smi 正常\
  • wsl -l -v 全是 2\
  • wsl --status 显示 GPU: NVIDIA\
  • 无 Hyper-V 冲突\
  • 已执行 wsl --update

WSL

  • nvidia-smi 正常\
  • 已安装 NVIDIA Container Toolkit

Docker Desktop

  • WSL2 backend\
  • 发行版已启用\
  • Linux Containers\
  • 能运行 CUDA 容器

WSL 里 nvidia-smi 不存在，是因为你的 WSL 环境还没安装或识别 NVIDIA 驱动。Windows 上的驱动不能自动映射到 WSL，需要单独配置 WSL 的 GPU 支持。解决方法如下：

1. 检查 WSL 版本

确保你使用的是 WSL 2：

bash
1wsl -l -v

输出中要显示你的 distro 是 VERSION 2。如果是 WSL 1，需要升级：

powershell
1wsl --set-version <distro_name> 2

2. 安装 WSL NVIDIA 驱动

去 NVIDIA 官网下载 CUDA WSL 版驱动： NVIDIA CUDA on WSL

安装后，WSL 执行：

bash
1nvidia-smi

应该能看到你的显卡信息。

注意：驱动版本需要支持你 Windows 上的 CUDA 版本（你是 580.97，CUDA 13）。

3. Docker GPU 支持

确保 Docker Desktop 已启用 GPU：

  1. 打开 Docker Desktop → Settings → Resources → WSL Integration。
  2. 勾选 Enable GPU support。
  3. 测试：
bash
1docker run --rm --gpus all nvidia/cuda:13.0-base nvidia-smi

如果能显示 GPU 信息，说明容器已经能访问显卡。

目前你在 WSL 内执行 nvidia-smi 提示找不到，是因为 WSL 内没有安装 NVIDIA 驱动，不是命令错。安装 WSL 版本的 NVIDIA 驱动即可解决。