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 (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 运行时找不到可用的驱动句柄，而不是设备不存在。
