Windows上Docker Desktop运行GPU容器需三重对齐：WSL2正确暴露/dev/dxg设备且nvidia-smi可见、Docker Desktop启用GPU支持并集成NVIDIA Container Toolkit、容器镜像及Compose配置使用新版devices声明语法，缺一不可。

Windows 上的 Docker Desktop 要跑 GPU 容器，**不是装完驱动 + Docker 就能直接 docker run --gpus all 成功的**。关键卡点在于 WSL2 是否真正打通了 GPU 设备通路，以及 Docker Desktop 是否识别到了 NVIDIA Container Toolkit 的运行时支持。很多报错如 nvidia-smi: command not found、failed to start shim: unknown runtime type nvidia-container-runtime 或 PyTorch 报 CUDA not available，基本都源于这层链路没对齐。

确认 WSL2 已加载 NVIDIA GPU 设备节点

WSL2 本身不自动暴露 GPU 设备文件，必须由 Windows 侧驱动注入。即使你装了最新版 GeForce 驱动，也要手动验证设备是否可见：

• 在 WSL2 发行版（如 Ubuntu）中执行：ls /dev/dxg —— 应返回一个设备文件；没有则说明驱动未向 WSL2 暴露 GPU
• 运行：nvidia-smi -L —— 若提示 No devices were found，不是容器问题，是 WSL2 根本没拿到 GPU
• 检查 Windows 驱动版本：必须 ≥ 515.65.01（2022 年后发布），旧驱动（如 470 系列）不支持 WSL2 GPU 直通
• 确保已执行：wsl --update 并重启 WSL2（wsl --shutdown 后再启动）

Docker Desktop 设置里必须启用 NVIDIA Container Toolkit

Docker Desktop 默认不激活 GPU 支持，哪怕你本地装了 nvidia-docker2，它也不会自动接管。必须显式开启：

• 打开 Docker Desktop → Settings → Resources → WSL Integration → 确保目标发行版（如 Ubuntu-22.04）已勾选
• Settings → General → 勾选 Use the WSL 2 based engine
• Settings → Experimental Features → 勾选 Enable GPU support for WSL（注意：该选项在 Docker Desktop 4.19+ 才稳定出现）
• 重启 Docker Desktop（不是仅 restart WSL，是整个 Desktop 应用）
• 验证是否生效：docker info | grep -i runtime 应看到 nvidia 在 Runtimes 列表中

docker run --gpus all 失败的常见原因与绕过方式

即使上述都对了，docker run --gpus all nvidia/cuda:12.2.0-base nvidia-smi 仍可能失败。这不是命令写错了，而是镜像或运行时不匹配：

Docker Hub

Docker Hub (hub.docker.com)。此技能适用于所有 Docker Hub 操作，包括读取、创建、更新和删除数据。只要任务涉及 Docker Hub，就使用此技能。

下载

• 基础镜像必须含 nvidia/cuda 或 nvcr.io/nvidia/cuda 官方源，自建 ubuntu:22.04 + 手动装 CUDA 会缺 libnvidia-container-tools 等关键组件
• 不要用 runtime: nvidia（Docker Compose v2.x 已弃用），新版必须用 deploy.resources.reservations.devices 声明 GPU
• 如果仍报 unknown device，临时降级测试：docker run --device /dev/dxg --device /usr/lib/wsl/lib/libcuda.so.1 -v /usr/lib/wsl/lib:/usr/lib/wsl/lib nvidia/cuda:12.2.0-base nvidia-smi —— 这是绕过 toolkit 直接挂载的“硬通”方式，仅用于定位问题
• PyTorch 容器检测不到 CUDA？检查是否漏设环境变量：NVIDIA_VISIBLE_DEVICES=all 和 NVIDIA_DRIVER_CAPABILITIES=compute,utility

docker-compose.yml 中声明 GPU 的正确写法

很多人照抄旧文档用 runtime: nvidia，结果服务起不来。Docker Compose v2.20+ 必须用资源预留语法：

services:
  trainer:
    image: pytorch/pytorch:2.3.0-cuda12.1-cudnn8-runtime
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=compute,utility

注意：capabilities: [gpu] 不可省略，否则容器内无法加载 libcuda.so；count: all 可换为 count: 1 或 device_ids: ["0"] 控制具体卡。

最易被忽略的一点：Docker Desktop 的 GPU 支持本质是 WSL2 → Windows 驱动 → 容器的三层透传，任意一层中断（比如 WSL2 内核未更新、Docker Desktop 版本太旧、驱动未启用 WSL 支持），都会导致容器里 nvidia-smi 能运行但 torch.cuda.is_available() 返回 False —— 因为 CUDA 运行时找不到可用的驱动句柄，而不是设备不存在。