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

# 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，依次执行以下命令：

```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，执行：

```powershell
wsl --set-default-version 2
```

### 2.3 查看可用的 Ubuntu 发行版

```powershell
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 为例）

```powershell
wsl --install -d Ubuntu-24.04
```

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

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

### 2.5 验证安装和 WSL 版本

```powershell
wsl -l -v
```

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

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

### 2.6 进入 Ubuntu 环境并更新系统

```powershell
wsl -d Ubuntu-24.04
```

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

```bash
sudo apt update && sudo apt upgrade -y
```

---

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

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

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

1. 访问 [NVIDIA 驱动下载页面](https://www.nvidia.com/Download/index.aspx) 或 [NVIDIA 官方 WSL 驱动下载页](https://developer.nvidia.com/cuda/wsl)
2. 选择您的显卡型号和操作系统（Windows 10/11 x64）
3. 下载驱动安装程序，确保选择支持 WSL 2 的版本（通常需要 515 及以上版本）
4. 运行安装程序，选择“精简安装”或“自定义安装”（确保勾选所有必要组件）
5. 完成安装后，建议重启计算机

### 3.2 验证 Windows 侧驱动安装

在 **Windows PowerShell**（非 WSL 中）执行：

```powershell
nvidia-smi
```

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

---

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

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

### 4.1 卸载旧版本 Docker（如有）

```bash
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 仓库（默认方式）

```bash
# 安装依赖工具
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 中的官方源配置，直接使用以下命令**：

```bash
# 安装依赖工具
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

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

```bash
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 服务。

```bash
sudo service docker start
```

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

```bash
sudo usermod -aG docker $USER
```

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

```powershell
wsl --terminate Ubuntu-24.04
wsl -d Ubuntu-24.04
```

### 4.6 验证 Docker 安装

```bash
docker run hello-world
```

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

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

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

```bash
# 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 镜像的拉取，您可以配置国内镜像加速器（如阿里云、中科大等）。这里以阿里云镜像加速器为例：

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

然后在 Ubuntu 终端中执行：

```bash
# 创建或修改 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
```

**验证加速器是否生效**：

```bash
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](https://developer.nvidia.com/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 为例（请根据页面提供的实际命令替换）：

```bash
# 下载安装包
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` 末尾添加：

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

然后执行：

```bash
source ~/.bashrc
```

### 5.4 验证 CUDA Toolkit 安装

```bash
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 官方源。

```bash
# 安装依赖
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

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

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

### 6.3 配置 Docker 运行时

```bash
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 服务

```bash
sudo systemctl restart docker
```

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

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

```bash
sudo update-alternatives --config iptables
```

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

### 6.6 重启 WSL 使配置生效

在 Windows PowerShell 中执行：

```powershell
wsl --shutdown
```

然后重新进入 WSL：

```powershell
wsl -d Ubuntu-24.04
```

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

#### 6.7.1 检查 nvidia-smi（在 WSL 内）

```bash
nvidia-smi
```

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

```bash
/usr/lib/wsl/lib/nvidia-smi
```

或将其添加到 PATH：

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

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

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

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

#### 6.7.3 运行 CUDA 测试容器

```bash
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 官网](https://developer.nvidia.com/cuda/wsl) 下载 |
| 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 服务启动失败

```bash
sudo service docker status
```

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

```bash
sudo dockerd &
```

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

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

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

```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 密钥下载失败，可以手动从官方源导入（阿里云使用与官方相同的密钥）：

```bash
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 容器

添加新评论

关于博主

文章分类

最受欢迎的文章

最近回复

其它