Windows 10 / 11 安装 Docker 并支持 GPU 完整操作指南

概述

本指南将指导您在 Windows 10 或 Windows 11 系统上，不使用 Docker Desktop，直接在 WSL 2 内安装 Docker Engine，并配置 GPU 支持。这种方案相比 Docker Desktop 更加轻量、节省资源，适合需要纯 Linux 容器开发环境的用户。

核心原理：WSL 2 采用独特的驱动映射机制——GPU 驱动只安装在 Windows 宿主侧，WSL 2 内的 Linux 通过 Windows 驱动的“代理”层访问 GPU。因此，在 WSL 2 内部无需也不能安装 Linux 版的 NVIDIA 驱动。

一、环境准备与系统要求

1.1 硬件与操作系统要求

组件	最低要求	推荐配置
Windows 版本	10 21H2 以上 / 11 22H2 以上	Windows 11 23H2 以上
WSL 内核	5.10.43.3 以上	最新内核
NVIDIA 驱动	550.xx 以上（支持 WSL 2）	最新 Game Ready / Studio 驱动
GPU	支持 CUDA 的 NVIDIA 显卡	RTX 30 或 40 系列

⚠️ 在开始之前，请确认您的 Windows 版本满足要求。可在 PowerShell 中运行 winver 查看版本号，或运行 systeminfo | findstr /B /C:"OS Name" /C:"OS Version" 进行确认。

1.2 检查 BIOS 虚拟化是否启用

在任务管理器的“性能”选项卡中，查看“虚拟化”状态是否为“已启用”。若未启用，需进入 BIOS/UEFI 设置开启 Intel VT-x 或 AMD-V。

二、启用 WSL 2 并安装 Ubuntu（命令行方式）

如果wsl版本过旧，可以参考 https://learn.microsoft.com/zh-cn/windows/wsl/install-manual

2.1 启用 WSL 和虚拟机平台功能

以管理员身份打开 PowerShell，依次执行以下命令：

# 启用适用于 Linux 的 Windows 子系统
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# 启用虚拟机平台功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

执行完毕后，重启计算机。

2.2 设置 WSL 2 为默认版本

重启后，以管理员身份打开 PowerShell，执行：

wsl --set-default-version 2

2.3 查看可用的 Ubuntu 发行版

wsl --list --online

输出示例：

NAME               FRIENDLY NAME
Ubuntu             Ubuntu
Ubuntu-24.04       Ubuntu 24.04 LTS
Ubuntu-22.04       Ubuntu 22.04 LTS
Ubuntu-20.04       Ubuntu 20.04 LTS
...

2.4 安装指定版本的 Ubuntu（以 Ubuntu 24.04 LTS 为例）

wsl --install -d Ubuntu-24.04

💡 如需安装 Ubuntu 22.04，则执行 wsl --install -d Ubuntu-22.04。

安装完成后，系统会自动打开该 Ubuntu 实例，并提示您创建用户名和密码——请务必记住，后续所有 sudo 操作都会用到。

2.5 验证安装和 WSL 版本

wsl -l -v

确保 VERSION 列显示为 2，STATE 列为 Running。

⚠️ 若 VERSION 显示为 1，可用 wsl --set-version <发行版名称> 2 进行转换，例如 wsl --set-version Ubuntu-24.04 2。

2.6 进入 Ubuntu 环境并更新系统

wsl -d Ubuntu-24.04

进入 Ubuntu 终端后，执行系统更新：

sudo apt update && sudo apt upgrade -y

三、在 Windows 上安装 NVIDIA 驱动（供 nvidia-smi 使用）

关键原则：GPU 驱动只需要在 Windows 宿主侧安装一次，WSL 2 内部绝对不能安装任何 Linux 版本的 NVIDIA 驱动，否则会导致冲突。

3.1 下载并安装支持 WSL 2 的 NVIDIA 驱动

访问 NVIDIA 驱动下载页面或 NVIDIA 官方 WSL 驱动下载页
选择您的显卡型号和操作系统（Windows 10/11 x64）
下载驱动安装程序，确保选择支持 WSL 2 的版本（通常需要 515 及以上版本）
运行安装程序，选择“精简安装”或“自定义安装”（确保勾选所有必要组件）
完成安装后，建议重启计算机

3.2 验证 Windows 侧驱动安装

在 Windows PowerShell（非 WSL 中）执行：

nvidia-smi

正常输出应显示 GPU 型号、驱动版本（例如 560.94）和 CUDA 版本信息。

四、在 WSL Ubuntu 中安装 Docker Engine（非 Desktop 版）

以下所有命令均在 WSL Ubuntu 终端中执行。

4.1 卸载旧版本 Docker（如有）

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove -y $pkg; done

4.2 设置 Docker 官方 APT 仓库（默认方式）

# 安装依赖工具
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 创建密钥目录
sudo install -m 0755 -d /etc/apt/keyrings

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

4.2.1 备选：使用阿里云 APT 源安装 Docker

如果 Docker 官方源访问缓慢或无法连接，可以使用阿里云镜像源。请跳过 4.2 中的官方源配置，直接使用以下命令：

# 安装依赖工具
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

# 添加阿里云 Docker GPG 密钥（阿里云使用与官方相同的密钥）
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置阿里云仓库
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

💡 阿里云源与 Docker 官方源使用相同的 GPG 密钥，因此可以直接替换 URL 部分。后续安装步骤完全一致。

4.3 安装 Docker Engine

无论使用官方源还是阿里云源，安装命令相同：

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

4.4 启动 Docker 服务

⚠️ 注意：WSL 2 默认不使用 systemd，需手动启动 Docker 服务。

sudo service docker start

4.5 将当前用户加入 docker 组（免 sudo 执行 docker 命令）

sudo usermod -aG docker $USER

⚠️ 该操作需要完全退出 WSL 并重新进入才能生效。关闭当前 Ubuntu 终端，然后在 PowerShell 中执行：

wsl --terminate Ubuntu-24.04
wsl -d Ubuntu-24.04

4.6 验证 Docker 安装

docker run hello-world

应看到类似 Hello from Docker! 的输出，表示 Docker 安装成功。

4.7 设置 Docker 随 WSL 自动启动（可选）

在 Ubuntu 的 ~/.bashrc 或 ~/.zshrc 末尾添加：

# Auto-start Docker daemon in WSL 2
if [ -f /etc/default/docker ] || [ -f /etc/docker/daemon.json ]; then
    pgrep dockerd > /dev/null 2>&1 || { sudo service docker start > /dev/null 2>&1 & }
fi

4.8 配置 Docker 镜像加速器（可选，但强烈推荐）

为了加速 Docker 镜像的拉取，您可以配置国内镜像加速器（如阿里云、中科大等）。这里以阿里云镜像加速器为例：

登录阿里云容器镜像服务控制台（如果没有账号，免费注册即可）
在左侧导航栏点击“镜像工具” → “镜像加速器”
复制您的专属加速器地址（格式如 https://xxxxx.mirror.aliyuncs.com）

然后在 Ubuntu 终端中执行：

# 创建或修改 Docker 配置文件
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
    "registry-mirrors": [
            "https://docker.1ms.run",
            "https://hub.rat.dev",
            "https://dockerproxy.net",
            "https://proxy.vvvv.ee"
      ]
}

EOF

# 重启 Docker 服务
sudo service docker restart

验证加速器是否生效：

docker info | grep -A 1 "Registry Mirrors"

4.9 配置 Docker 的存储路径（可选，但强烈推荐）

可以查看本站的《在 Ubuntu 系统中修改 Docker 和 Containerd 数据存储位置》

五、在 WSL Ubuntu 中安装 CUDA Toolkit

⚠️ 重要提醒：CUDA Toolkit 的安装方式与纯 Linux 环境不同。必须选择 不包含驱动的 Linux 安装包，因为驱动已经由 Windows 侧的 NVIDIA 驱动提供。切勿选择 cuda、cuda-12-x 或 cuda-drivers 等元包，这些包会在 WSL 2 内部尝试安装 Linux NVIDIA 驱动。

5.1 访问 NVIDIA CUDA Toolkit 下载页面

前往 NVIDIA Developer CUDA Downloads，选择以下选项：

Operating System: Linux
Architecture: x86_64
Distribution: WSL-Ubuntu
Version: 2.0（或对应版本）
Installer Type: deb (local)

5.2 下载并安装 CUDA Toolkit（WSL 专用版本）

以 CUDA 12.6 / 13.3 为例（请根据页面提供的实际命令替换）：

# 下载安装包
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb

# 安装密钥
sudo dpkg -i cuda-keyring_1.1-1_all.deb

# 更新源并安装 CUDA Toolkit（不包含驱动）
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-6
# sudo apt-get -y install cuda-toolkit-13-3

💡 如果安装过程中提示需要 cuda-cudart-xx 等依赖，直接继续安装即可。

5.3 配置环境变量

在 ~/.bashrc 末尾添加：

export PATH=/usr/local/cuda-12/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-12/lib64:$LD_LIBRARY_PATH

然后执行：

source ~/.bashrc

5.4 验证 CUDA Toolkit 安装

nvcc --version

六、安装 NVIDIA Container Toolkit（GPU 容器支持）

NVIDIA Container Toolkit 是实现 Docker 容器调用 GPU 的关键组件，它让容器能够“透视”到宿主机的 GPU 设备。如果因网络环境问题，可以查看本站《在Ubuntu 中安装 NVIDIA Container Toolkit》的方法

6.1 添加 NVIDIA Container Toolkit 官方软件源

⚠️ 注意：Ubuntu 自带源中的 nvidia-container-toolkit 版本过旧，必须使用 NVIDIA 官方源。

# 安装依赖
sudo apt-get update && sudo apt-get install -y curl gnupg2 ca-certificates

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

# 添加软件源
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

6.2 安装 NVIDIA Container Toolkit

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

💡 nvidia-container-toolkit 是新一代工具包，已取代旧版的 nvidia-docker2。

6.3 配置 Docker 运行时

sudo nvidia-ctk runtime configure --runtime=docker

该命令会自动修改 Docker 的配置文件，将 nvidia 设置为默认运行时。

⚠️ 注意：此命令会修改 /etc/docker/daemon.json。如果您之前在 4.8 节中已配置了镜像加速器，该命令会保留原有配置并增加 runtimes 和 default-runtime 字段。如果执行时提示文件已存在并询问是否覆盖，请选择 保留当前配置（输入 n）然后手动合并。推荐做法：先配置镜像加速器，再执行 nvidia-ctk runtime configure，该工具会自动合并。

6.4 重启 Docker 服务

sudo systemctl restart docker

⚠️ 如果在 WSL 2 中提示 systemctl 命令不可用，则使用 sudo service docker restart。

6.5 设置 iptables 兼容性（如遇网络问题）

sudo update-alternatives --config iptables

当提示时，选择编号为 1 的路径 /usr/sbin/iptables-legacy。

6.6 重启 WSL 使配置生效

在 Windows PowerShell 中执行：

wsl --shutdown

然后重新进入 WSL：

wsl -d Ubuntu-24.04

6.7 验证 GPU 加速是否正常工作

6.7.1 检查 nvidia-smi（在 WSL 内）

nvidia-smi

正常输出应显示 GPU 使用状况。如果提示 command not found，不用担心，因为 nvidia-smi 是通过 Windows 驱动映射过来的，可尝试使用以下路径：

/usr/lib/wsl/lib/nvidia-smi

或将其添加到 PATH：

export PATH=/usr/lib/wsl/lib:$PATH

6.7.2 在 Docker 容器中运行 nvidia-smi（终极验证）

docker run --rm --gpus all ubuntu nvidia-smi

如果看到 GPU 信息正常输出，说明环境配置完全成功。

6.7.3 运行 CUDA 测试容器

docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

七、常见问题与排错

问题 1：`nvidia-smi` 在 WSL 中提示 command not found

原因	解决方案
Windows 侧的 NVIDIA 驱动不支持 WSL 2	升级到 515 以上版本的驱动，从 NVIDIA 官网下载
WSL 版本不是 WSL 2	在 PowerShell 中运行 `wsl --set-version <发行版名称> 2`
驱动映射文件不在 PATH 中	使用 `/usr/lib/wsl/lib/nvidia-smi` 或添加该路径到 PATH

问题 2：Docker 容器中无法访问 GPU

原因	解决方案
NVIDIA Container Toolkit 未安装	按照第六章步骤安装 `nvidia-container-toolkit`
Docker 未配置 nvidia 运行时	运行 `sudo nvidia-ctk runtime configure --runtime=docker`，重启 Docker 服务
WSL 未重启	在 PowerShell 中执行 `wsl --shutdown`，然后重新进入 WSL
容器命令中未使用 `--gpus all` 参数	运行容器时加上 `--gpus all` 或 `--gpus device=0`
镜像加速器配置导致 daemon.json 冲突	手动检查 `/etc/docker/daemon.json`，确保同时包含 `registry-mirrors` 和 `runtimes` 字段

问题 3：CUDA 版本不兼容

现象	解决方案
容器运行时提示 CUDA 版本不匹配	检查 Windows 驱动支持的 CUDA 版本（通过 `nvidia-smi` 顶部查看），选择兼容的容器镜像
旧的 CUDA 版本（≤10）不支持 WSL 2	升级到 CUDA 11+ 版本

问题 4：Docker 服务启动失败

sudo service docker status

如果状态显示 not running，尝试：

sudo dockerd &

或检查 Docker 配置文件 /etc/docker/daemon.json 是否正确，然后重试启动。

问题 5：WSL 版本显示为 1.x

在 Windows PowerShell（管理员）中执行：

wsl --set-default-version 2
wsl --set-version <发行版名称> 2

问题 6：安装 CUDA Toolkit 时提示尝试安装 Linux 驱动

这是 WSL 环境中最容易出错的步骤。务必选择 WSL-Ubuntu 特定的安装包，而不是标准的 Linux 安装包。标准安装包会尝试安装 Linux 驱动，与 Windows 驱动冲突。

问题 7：Docker pull 镜像慢

请参考 4.8 节配置镜像加速器。

问题 8：阿里云 APT 源安装 Docker 时 GPG 密钥错误

如果阿里云源的 GPG 密钥下载失败，可以手动从官方源导入（阿里云使用与官方相同的密钥）：

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

然后继续使用阿里云仓库地址。

八、最终验证清单

完成全部步骤后，依次执行以下命令，确认所有环节正常：

验证项	命令	预期结果
Windows 驱动	PowerShell 中 `nvidia-smi`	正常显示 GPU 信息
WSL 版本	PowerShell 中 `wsl -l -v`	VERSION 列为 2
Docker 运行	`docker run hello-world`	显示 "Hello from Docker!"
WSL 内 nvidia-smi	`nvidia-smi` 或 `/usr/lib/wsl/lib/nvidia-smi`	显示 GPU 状态
容器内 GPU 支持	`docker run --rm --gpus all ubuntu nvidia-smi`	正常显示 GPU 信息
CUDA Toolkit	`nvcc --version`	显示 CUDA 版本信息
Docker 镜像加速器	`docker info \| grep -A 1 "Registry Mirrors"`	显示配置的镜像地址

全部验证通过后，您就可以在 Windows 上通过 WSL 2 和 Docker Engine 使用 GPU 进行容器化开发了。

附录：完整环境架构图

┌─────────────────────────────────────────────────────────────┐
│                        Windows 宿主                          │
│  ┌───────────────────────────────────────────────────────┐  │
│  │          NVIDIA GPU 驱动（Game Ready / Studio）         │  │
│  │                     （唯一驱动安装位置）                   │  │
│  └───────────────────────────────────────────────────────┘  │
│                              │                               │
│                              ▼                               │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                    WSL 2 轻量虚拟机                      │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │                 Ubuntu 22.04/24.04               │  │  │
│  │  │  ┌───────────┐  ┌───────────────────────────┐  │  │  │
│  │  │  │ CUDA      │  │    NVIDIA Container       │  │  │  │
│  │  │  │ Toolkit   │  │        Toolkit            │  │  │  │
│  │  │  └───────────┘  └─────────────┬─────────────┘  │  │  │
│  │  │                               │                 │  │  │
│  │  │                               ▼                 │  │  │
│  │  │  ┌─────────────────────────────────────────┐   │  │  │
│  │  │  │            Docker Engine                │   │  │  │
│  │  │  │   (配置镜像加速器 + nvidia运行时)         │   │  │  │
│  │  │  └─────────────────────────────────────────┘   │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Windows 环境中，运行支持 GPU 的 Docker 容器