WSL 配 GPU 用 Docker 的折腾指南（2026 年版）

在 WSL2 里头跑带 GPU 的 Docker 容器，这是做 AI 或者搞数据科学的人逃不过的一课。但自从 Docker 26 来了，再加上 NVIDIA 那套 CDI 的玩意儿，还有 CUDA 13 和 Ubuntu 24，不少人栽了跟头。

我这篇文章就是想带你从头开始，把那些坑一个个填上，最后弄个稳当的 GPU 加速环境出来。

你大概率会遇到这些错误：

• CDI 那边说找不到供应商：no known GPU vendor found
• 跑不起来，提示 nvidia-container-runtime not found
• 要是用 AMD 卡，会报 AMD CDI spec not found
• 配置冲突的提示：directives are specified both as a flag and in config

---

第一章：先把环境搭好，验证一下

1.1 你得有的东西（2026 年比较推荐的配置）

部件	最低要求	建议配置
Windows	10 21H2 以上 / 11 22H2 以上	Windows 11 23H2 以上
WSL 内核	5.15.90.1 以上	6.x 内核
Ubuntu	22.04 LTS	24.04 LTS
Docker	25.0 以上	26.0 以上
NVIDIA 驱动（在 Windows 上）	550.xx 以上	最新的 Game Ready / Studio 版本
GPU	至少 RTX 20 系	RTX 30 或 40 系

1.2 先确认 WSL 能识别 GPU

在装 Docker 相关的一堆东西之前，得先看看 WSL 自己能不能认出 GPU：

# 在 WSL 的终端里头跑这个
nvidia-smi

✅ 正常的话会显示 GPU 型号，比如 NVIDIA GeForce RTX 4090，还有 CUDA 版本和显存情况。

❌ 要是跑不出来，你就按这个顺序来排查：

1. 在 Windows 上装最新的 NVIDIA 驱动
2. 把 WSL 彻底关掉再开：wsl --shutdown
3. 看看是不是用的 WSL 2：wsl -l -v（VERSION 那一列得是 2）

---

第二章：把 NVIDIA 的工具包装进去

2.1 添加官方软件源

注意：Ubuntu 自带的源里头，nvidia-container-toolkit 的版本早就过时了，非得用官方源不可。

# 1. 先装些依赖
sudo apt-get update && sudo apt-get install -y curl gnupg2 ca-certificates

# 2. 把 NVIDIA 的 GPG 密钥加进来
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | \
    sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# 3. 加软件源
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    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

2.2 安装工具包

# 更新一下再安装
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit nvidia-container-runtime

# ✅ 看看装没装成功
nvidia-ctk --version
which nvidia-container-runtime

---

第三章：CDI 这玩意儿是啥，怎么配

3.1 CDI 解释一下

CDI（Container Device Interface）是 CNCF 弄出来的容器设备接口标准，用来让容器能统一访问主机上的硬件。Docker 25 以后默认就用 CDI 来处理 GPU 设备了。

我碰过很多次，CDI 报错九成是因为规范文件没生成好或者坏了。

3.2 生成 CDI 规范文件

# 1. 先建个目录
sudo mkdir -p /etc/cdi

# 2. 用官方工具生成文件
sudo nvidia-ctk cdi generate \
    --output=/etc/cdi/nvidia.yaml \
    --device-name-strategy=index \
    --vendor=nvidia.com

# 3. ✅ 看看生成的文件对不对
cat /etc/cdi/nvidia.yaml

3.3 这个文件长啥样

一个正常的 /etc/cdi/nvidia.yaml 大概是这样的：

cdiVersion: "0.6.0"
kind: nvidia.com/gpu           # ⚠️ 这个必须完全一样！
devices:
  - name: "0"                  # GPU 设备的索引
    containerEdits:
      deviceNodes:
        - path: /dev/nvidia0
        - path: /dev/nvidiactl
        - path: /dev/nvidia-uvm
        - path: /dev/nvidia-uvm-tools

---

第四章：Docker 怎么配比较好

4.1 daemon.json 里的配置

编辑或者创建这个文件： /etc/docker/daemon.json

{
    "iptables": false,
    "hosts": [
        "unix:///var/run/docker.sock"
    ],
    "runtimes": {
        "nvidia": {
            "path": "/usr/bin/nvidia-container-runtime",
            "runtimeArgs": []
        }
    },
    "cdi-spec-dirs": [
        "/etc/cdi",
        "/var/run/cdi"
    ]
}

4.2 WSL 启动脚本

弄个脚本来启动 Docker： /usr/local/bin/start-docker.sh

#!/bin/bash

if pgrep -x "dockerd" > /dev/null; then
    echo "✅ Docker 已经在运行了"
    exit 0
fi

echo "🚀 准备启动 Docker..."
nohup /usr/bin/dockerd > /var/log/docker.log 2>&1 &

sleep 2

if pgrep -x "dockerd" > /dev/null; then
    echo "✅ Docker 启动成功"
else
    echo "❌ 启动失败"
    exit 1
fi

记住一条：启动脚本里头别加命令行参数（比如 --host、--iptables），这些统一用 daemon.json 管，免得冲突。

4.3 重启 Docker 让配置生效

# 给脚本加点执行权限
sudo chmod +x /usr/local/bin/start-docker.sh

# 重启 Docker
pkill dockerd && sleep 2 && sudo /usr/local/bin/start-docker.sh

# ✅ 看看配置有没有起作用
docker info | grep -A5 Runtimes
docker info | grep -i cdi

---

第五章：版本得匹配好

5.1 CUDA 镜像选哪个

镜像标签	CUDA 版本	Ubuntu 版本	适合干啥
nvidia/cuda:13.1.2-base-ubuntu24.04	13.1.2	24.04 LTS	✅ 推荐，最新稳定版
nvidia/cuda:12.6.3-base-ubuntu22.04	12.6.3	22.04 LTS	兼容性比较好
nvidia/cuda:11.8.0-base-ubuntu22.04	11.8.0	22.04 LTS	旧框架也能用（PyTorch/TensorFlow）

5.2 驱动版本的要求

CUDA 版本	最低 NVIDIA 驱动版本（在 Windows 上）
CUDA 13.x	≥ 550.xx
CUDA 12.x	≥ 525.xx
CUDA 11.8	≥ 450.xx

在 WSL 里头有个关键点：Windows 上的驱动版本决定了 WSL 里面能支持的最高 CUDA 版本。

---

第六章：CDI 和传统 Runtime 比一下

6.1 技术架构上有什么不同

特性	传统的 --runtime=nvidia	CDI 的 --gpus all
技术标准	NVIDIA 自己的方案	CNCF 的开放标准
什么时候引入	Docker 19.03	Docker 25.0 以后
设备怎么发现	nvidia-container-runtime-hook	容器运行时原生支持
配置放哪	daemon.json 的 runtime	/etc/cdi/*.yaml
多厂商支持	只支持 NVIDIA	NVIDIA / AMD / Intel 都行
WSL2 兼容性	✅ 已经很成熟了	⚠️ 2026 年还在完善

6.2 参数怎么用的不同

✅ 传统方法（稳当，WSL 里头推荐）：

# 方式 A：runtime 加上环境变量
docker run --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all ...

# 方式 B：只指定 runtime
docker run --runtime=nvidia ...

✅ CDI 方法（新标准）：

# 方式 A：所有 GPU
docker run --gpus all ...

# 方式 B：指定 GPU 编号
docker run --gpus 0 ...
docker run --gpus '"device=0,1"' ...

6.3 推荐怎么用的策略

🎯 在 WSL2 里头（2026 年），我推荐这样来：

# ✅ 最好先用：传统方法（最稳）
docker run --rm --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all \
    nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi

# ✅ 备选：CDI 方法（配置正确才行）
docker run --rm --gpus all \
    nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi

环境	推荐方式	原因
WSL2 开发机	--runtime=nvidia	稳定性优先
原生 Linux	--gpus all	CDI 支持已经完善了
Kubernetes 集群	CDI	这是生态标准
生产环境	传统方式	成熟可靠

别犯这个错：两种方法别同时用！docker run --runtime=nvidia --gpus all ... 会冲突的。

---

✅ 第七章：验证一下

7.1 基本 GPU 可用性测试

# 测试 1：CDI 模式
docker run --rm --gpus all nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi

# 测试 2：传统兼容模式
docker run --rm --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all \
    nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi

7.2 跑个性能基准

# nbody 粒子模拟基准测试
docker run --rm --gpus all nvcr.io/nvidia/k8s/cuda-sample:nbody nbody -gpu -benchmark

✅ 正常的话会输出：

GPU Device 0: "NVIDIA GeForce RTX 4090" with compute capability 8.9
16384 bodies, total time for 10 iterations: 12.345 ms
= 4357.801 single-precision GFLOP/s

---

🔧 第八章：常见问题的解决办法

8.1 配置冲突

错误提示： directives are specified both as a flag and in the configuration file

怎么解决：

• 看看启动脚本里头有没有重复的命令行参数

• 统一用 daemon.json 管所有配置

• 删掉 dockerd 启动时的 --iptables、--host 这些参数

8.2 CDI 供应商发现失败

错误提示： failed to discover GPU vendor from CDI: no known GPU vendor found

怎么解决：

# 重新生成 CDI 文件
sudo rm -f /etc/cdi/*.yaml
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# 看看 kind 字段对不对
grep "kind:" /etc/cdi/nvidia.yaml

8.3 运行时找不到

错误提示： exec: "nvidia-container-runtime": executable file not found in $PATH

怎么解决：

# 看看文件在不在
ls -la /usr/bin/nvidia-container-runtime

# 如果不在，重新安装
sudo apt-get install --reinstall nvidia-container-runtime

8.4 AMD 的 CDI 报错

错误提示： AMD CDI spec not found

怎么解决：

• 这是 Docker 有个 bug，会错误地去查找 AMD 设备

• 确保 /etc/cdi/ 目录下只有 nvidia.yaml

• 删掉其他无关的 CDI 文件

---

⚡ 第九章：高级点儿的配置

9.1 多 GPU 怎么配

# 自动检测并生成多 GPU 配置
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

# 测试指定 GPU 运行
docker run --rm --gpus 0 nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi
docker run --rm --gpus 1 nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi

9.2 Windows 驱动更新后要做的

⚠️ 每次在 Windows 上更新 NVIDIA 驱动之后，必须执行：

# Windows 的命令提示符
wsl --shutdown

# 重新打开 WSL 之后
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
pkill dockerd && sleep 2 && sudo /usr/local/bin/start-docker.sh

9.3 Docker Desktop 用户注意

如果你用 Docker Desktop for Windows：

1. 在 Docker Desktop 的设置里头 → Resources → WSL Integration → 启用你的 WSL 发行版

2. 不需要在 WSL 里头单独装 Docker

3. NVIDIA Container Toolkit 由 Docker Desktop 自动管理

---

✅ 第十章：做完之后核对一遍

等所有配置弄完，逐项检查：

[ ] nvidia-smi 在 WSL 里头正常显示 GPU 信息

[ ] nvidia-ctk --version 命令能跑

[ ] /etc/cdi/nvidia.yaml 文件存在，格式也对

[ ] /etc/docker/daemon.json 里配置了 nvidia runtime 和 CDI 路径

[ ] Docker 启动脚本里头没有冲突的命令行参数

[ ] docker run --rm --gpus all nvidia/cuda:13.1.2-base-ubuntu24.04 nvidia-smi 测试通过

[ ] nbody 基准测试能正常跑

---

📝 最后说几句

WSL2 加 Docker 加 GPU 加速的配置虽然坑不少，但只要明白 CDI 机制和配置冲突的根本原因，就能弄出一个稳定可靠的开发环境。

核心要点记一下：

1. 永远用 NVIDIA 官方源装 container-toolkit

2. 统一用 daemon.json 管 Docker 配置，别搞命令行参数冲突

3. CDI 规范文件是 --gpus all 能工作的关键

4. Windows 驱动更新后得重新生成 CDI 文件

5. WSL2 里头最好用 --runtime=nvidia 传统方式，这样最稳

希望这篇指南能帮你在 WSL 里头顺利配好 Docker GPU 加速环境。

原创技术博客 · 开源项目分享 · AI全栈创作社区 idao.fun