Docker 使用 Nvidia 显卡

# 前言

本文介绍如何在 Docker 容器中使用 Nvidia 显卡，适用于深度学习、AI 推理等需要 GPU 加速的场景。

提示

以下环境均为 Ubuntu 22.04，其他版本请根据实际情况调整。

# 一、主机显卡查看

# 查看主机显卡型号

lspci | grep NVIDIA

# 查看详细显卡信息

lspci -v -s $(lspci | grep -i 'nvidia' | head -n 1 | cut -d' ' -f1)

# 二、安装 Nvidia 驱动

主机上必须先安装 Nvidia 驱动，容器才能使用 GPU。

# 方式一：手动安装指定版本

进入 Nvidia 官网 (opens new window) 下载对应系统驱动，或参考 Ubuntu 官方安装文档 (opens new window)。

# 设置变量（根据需要修改）
version=570.133.20
distro=ubuntu2204
arch_ext=amd64.deb

# 安装依赖
apt install linux-headers-$(uname -r)

# 下载并添加 Nvidia 源
wget https://developer.download.nvidia.com/compute/nvidia-driver/$version/local_installers/nvidia-driver-local-repo-$distro-$version_$arch_ext.deb
dpkg -i nvidia-driver-local-repo-$distro-$version_$arch_ext.deb

# 更新源并导入密钥
apt update
cp /var/nvidia-driver-local-repo-$distro-$version/nvidia-driver-*-keyring.gpg /usr/share/keyrings/

# 查看可用驱动版本
apt search nvidia-driver

# 安装驱动
apt install nvidia-driver-570

# 方式二：自动安装推荐版本（推荐）

# 查看当前系统推荐的 NVIDIA 驱动版本
sudo ubuntu-drivers devices

# 自动安装推荐驱动
sudo ubuntu-drivers autoinstall

# 验证驱动安装

nvidia-smi

正常输出示例：

Thu May 22 14:43:38 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 570.133.20             Driver Version: 570.133.20     CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  Tesla T4                       Off |   00000000:00:07.0 Off |                    0 |
| N/A   34C    P8              9W /   70W |       8MiB /  15360MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|    0   N/A  N/A            1140      G   /usr/lib/xorg/Xorg                        4MiB |
+-----------------------------------------------------------------------------------------+

# 三、安装 CUDA Toolkit（可选）

提示

深度学习等需要 CUDA 环境的场景才需要安装，如果只需 GPU 加速可跳过此步骤。

参考 CUDA 官网 (opens new window)

# 下载并添加 CUDA 源
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600

wget https://developer.download.nvidia.com/compute/cuda/12.9.0/local_installers/cuda-repo-ubuntu2204-12-9-local_12.9.0-575.51.03-1_amd64.deb
sudo dpkg -i cuda-repo-ubuntu2204-12-9-local_12.9.0-575.51.03-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2204-12-9-local/cuda-*-keyring.gpg /usr/share/keyrings/

# 更新源并安装
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-9

# 验证 CUDA 安装

nvcc --version

# 四、安装 nvidia-container-toolkit

这是让 Docker 容器能够使用 GPU 的关键组件。

参考 Nvidia 官方文档 (opens new window)

# 添加 Nvidia 源

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

# 安装 toolkit

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

# 五、配置 Docker 使用 Nvidia Runtime

# 配置 Docker

sudo nvidia-ctk runtime configure --runtime=docker

# 重启 Docker

sudo systemctl restart docker

# 验证配置

查看 Docker 配置文件：

cat /etc/docker/daemon.json

应该出现如下结果：

{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}

提示

如果已有其他配置，请合并到现有配置中，不要直接覆盖。

# 六、容器中使用 GPU

# Docker CLI 使用

# 基本参数说明

参数	说明
`--gpus all`	将所有 GPU 分配给容器
`--gpus "device=0"`	只分配 GPU 0
`--gpus "device=0,1"`	分配 GPU 0 和 1
`--gpus '"device=0,1"'`	分配 GPU 0 和 1（某些 shell 需要额外引号）
`--gpus 2`	分配任意 2 个 GPU

# 测试容器

docker run --rm --gpus all nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

成功输出会显示容器内的 GPU 信息。

# 指定 GPU

# 只使用第一块 GPU
docker run --rm --gpus "device=0" nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

# 使用指定多块 GPU
docker run --rm --gpus "device=0,2" nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

# 使用任意两块 GPU
docker run --rm --gpus 2 nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

# GPU 资源限制

# 限制使用 GPU 0 的一半内存
docker run --rm --gpus '"device=0"' --shm-size=1g nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

# Docker Compose 使用

# 基本配置（推荐写法）

services:
  cuda12:
    image: nvidia/cuda:12.8.0-runtime-ubuntu22.04
    container_name: cuda12.8
    restart: "no"
    environment:
      NVIDIA_DRIVER_CAPABILITIES: compute,video,utility
    stdin_open: true
    tty: true
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    command: ["nvidia-smi"]

# 指定 GPU

services:
  ai-service:
    image: your-ai-image:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              device_ids: ['0', '1']  # 指定 GPU 0 和 1
              capabilities: [gpu]

# 环境变量说明

环境变量	说明
`NVIDIA_DRIVER_CAPABILITIES`	GPU 能力列表，如 `compute,utility,video,graphics`
`NVIDIA_VISIBLE_DEVICES`	指定可见 GPU，如 `0,1` 或 `all`

查看变量值：

echo $NVIDIA_DRIVER_CAPABILITIES
#同时可以看 GPU 可见性
echo $NVIDIA_VISIBLE_DEVICES

查看容器：

docker inspect container_name  --format '{{json .HostConfig.DeviceRequests}}' | jq

示例：

services:
  ai-service:
    image: your-ai-image:latest
    environment:
      NVIDIA_VISIBLE_DEVICES: 0,1  # 只使用 GPU 0 和 1
      NVIDIA_DRIVER_CAPABILITIES: compute,utility

提示

配置了 default-runtime: nvidia 后，docker-compose 配置可省略 runtime: nvidia

# 七、常见问题

# 1. nvidia-container-toolkit 安装失败

问题：E: Unable to locate package nvidia-container-toolkit

解决：

# 检查源是否正确添加
cat /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 手动添加源（适用于 Ubuntu 22.04）
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. 容器内无法识别 GPU

问题：docker: Error response from daemon: could not select device driver

解决：

# 确认 nvidia-container-toolkit 已安装
dpkg -l | grep nvidia-container-toolkit

# 重新配置 Docker
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# 3. 多 GPU 环境下指定 GPU 无效

问题：设置了 --gpus "device=0" 但容器仍能看到所有 GPU

解决：检查 NVIDIA_VISIBLE_DEVICES 环境变量

docker run --rm --gpus "device=0" -e NVIDIA_VISIBLE_DEVICES=0 nvidia/cuda:12.8.0-runtime-ubuntu22.04 nvidia-smi

# 4. GPU 内存不足

解决：

调整 --shm-size 参数增加共享内存
使用 --gpus 参数限制 GPU 数量
考虑使用模型量化或梯度累积等技术

# 八、参考链接

#docker #nvidia #gpu #cuda

上次更新: 2026/01/16, 08:01:40

← Dockerfile RedConfig配置→