Windows 下 Docker + WSL2 + NVIDIA GPU 完整配置指南（2026 最新实测）

一句话总结 ：要在 Windows 上用 Docker 调用 NVIDIA GPU，必须在 WSL2 的 Linux 终端中操作 ，且需使用 runtime 镜像。

💡 为什么需要这套组合？

很多开发者习惯在 Windows 上工作，但深度学习、AI 推理等任务又严重依赖 Linux + CUDA 生态。过去只能装双系统或忍受虚拟机性能损失。

如今，WSL2 + Docker Desktop + NVIDIA 驱动三位一体，让你在 Windows 中获得近乎原生的 GPU 加速体验。

✅ 前提条件

Windows 10 版本 2004 或更高（Build 19041+）或 Windows 11
NVIDIA 显卡（GTX 10 系列、RTX 20/30/40 系列等，计算能力 ≥ 3.5）
至少 8GB 内存（推荐 16GB+）
BIOS 中已启用 虚拟化（Intel VT-x / AMD-V）

🔧 详细安装步骤（从零开始）

第一步：启用 WSL 和虚拟机平台

以 管理员身份 打开 PowerShell（右键开始菜单 → Windows PowerShell (管理员)），运行：

powershell 复制代码

# 启用 WSL 和虚拟机平台
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

⚠️ 执行后必须重启电脑。

第二步：安装 WSL2 内核更新

下载并安装 WSL2 Linux 内核更新包
安装完成后，设置 WSL2 为默认版本：

powershell 复制代码

wsl --set-default-version 2

第三步：安装 Linux 发行版（如 Ubuntu）

打开 Microsoft Store
搜索 "Ubuntu" → 选择 Ubuntu 22.04 LTS（推荐）或最新 LTS 版
点击"安装"
安装完成后，从开始菜单启动它
首次启动会要求创建 用户名和密码（记住！这是你的 Linux 用户凭证）

📌 此时你已拥有一个完整的 Linux 子系统！

第四步：安装 NVIDIA 驱动（仅需在 Windows 安装！）

访问 NVIDIA 驱动下载页
选择你的显卡型号 → 操作系统选 "Windows 10/11"
下载 Game Ready Driver (GRD) 或 Studio Driver（两者均支持 WSL2）
安装时勾选 "执行清洁安装"
安装完成后重启电脑

✅ 验证：重启后，在 Windows 桌面按 Win + R → 输入 cmd → 运行：
cmd 复制代码
nvidia-smi
如果看到 GPU 信息，说明驱动安装成功。
📌 重要：不要在 WSL2 的 Ubuntu 中安装 NVIDIA 驱动！WSL2 会自动继承 Windows 驱动。

第五步：安装 Docker Desktop for Windows

下载 Docker Desktop for Windows
运行安装程序（建议勾选 "Use WSL 2 based engine"）
安装完成后，登录 Docker 账号（可选但推荐）
打开 Docker Desktop 设置（右下角托盘图标 → Settings）

在 Settings 中确认以下选项：

General → ✅ Use the WSL 2 based engine
Resources → WSL Integration → ✅ Enable integration with your installed WSL distro（如 Ubuntu-22.04）

💡 启用集成后，Docker 命令会自动在 WSL2 中可用，无需额外配置 PATH。

🔍 详细检查步骤（验证是否成功）

检查 1：确认 WSL2 版本

在 PowerShell 中运行：

powershell 复制代码

wsl -l -v

✅ 正确输出示例：

复制代码

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

如果 VERSION 是 1，请升级：wsl --set-version Ubuntu-22.04 2

检查 2：在 WSL2 中验证 GPU 可见性

从开始菜单打开 Ubuntu
运行：
bash 复制代码
```
nvidia-smi
```

✅ 成功输出 GPU 型号、驱动版本、显存等信息

❌ 失败可能原因：NVIDIA 驱动未更新（需 ≥ 515.48.07）

📌 注意：此命令在 WSL2 中能运行，证明 Windows 驱动已正确暴露给子系统。

检查 3：测试 Docker GPU 支持（关键！）

仍在 Ubuntu 终端中执行：

bash 复制代码

# 拉取官方 runtime 镜像（含 nvidia-smi）
docker pull nvidia/cuda:12.4.0-runtime-ubuntu22.04

# 运行 GPU 测试
docker run --rm --gpus all nvidia/cuda:12.4.0-runtime-ubuntu22.04 nvidia-smi

✅ 成功输出与 nvidia-smi 相同的 GPU 信息

✅ 容器退出后自动删除（因 --rm）

⚠️ 必须在 WSL2 终端运行！ 在 Windows CMD/PowerShell 中运行会失败或无法访问 GPU。

检查 4：验证 CUDA 版本兼容性

容器内显示的 "CUDA Version: 12.4" 是驱动支持的最高 CUDA 版本，不是容器实际使用的版本。

要查看容器内真实 CUDA 版本：

bash 复制代码

docker run --rm --gpus all nvidia/cuda:12.4.0-runtime-ubuntu22.04 cat /usr/local/cuda/version.txt

输出应为：

复制代码

CUDA Version 12.4.0

🛠️ 常见问题与解决

问题	解决方案
`nvidia-smi: command not found` in container	改用 `runtime` 或 `devel` 镜像，勿用 `base`
`could not select device driver "" with capabilities: [[gpu]]`	确认在 WSL2 终端运行；重启 Docker Desktop
拉取镜像时报 `failed size validation`	在 WSL2 中执行 `docker system prune -af`，重启 Docker Desktop
WSL2 中 `nvidia-smi` 报错	升级 Windows 端 NVIDIA 驱动至最新版（≥ 550）
Docker Desktop 无法连接 WSL2	在 PowerShell 执行 `wsl --shutdown`，再重启 Docker

🌟 总结

通过以上步骤，你已完成：

✅ WSL2 安装与配置
✅ NVIDIA 驱动正确安装（仅 Windows 端）
✅ Docker Desktop 与 WSL2 集成
✅ GPU 在 Docker 容器中可用

现在，你可以无缝运行 PyTorch、TensorFlow、Ollama、Stable Diffusion 等支持 CUDA 的应用，享受本地 GPU 加速！

记住黄金法则 ：所有涉及 GPU 的 Docker 命令，必须在 WSL2 的 Linux 终端中执行。

日期：2026 年 4 月 13 日
测试环境：Windows 11 23H2 + RTX 4070 + Docker Desktop 4.30 + NVIDIA Driver 550.42 + Ubuntu 22.04 LTS