在 Ubuntu 上安装 nvidia-container-toolkit并使用

本文介绍在Ubuntu系统上安装和配置NVIDIA Container Toolkit的完整流程。首先需要确保已安装NVIDIA驱动和Docker Engine（≥19.03）。安装步骤包括：配置NVIDIA软件仓库、安装工具包、设置Docker默认运行时，并重启Docker服务。验证时可通过运行nvidia-smi命令检查GPU是否正常工作。文章还详细说明了如何让多个容器共享GPU资源，包括直接

渐变-重构

1200人浏览 · 2025-08-03 15:06:38

渐变-重构 · 2025-08-03 15:06:38 发布

在 Ubuntu 上安装 nvidia-container-toolkit并使用

1. 前置条件

已安装符合驱动版本的 NVIDIA GPU 与官方驱动（nvidia-smi 正常工作）。
已安装 Docker Engine ≥ 19.03，且用户可运行 docker 命令。

2. 配置 NVIDIA 软件仓库

sudo apt-get update
sudo apt-get install -y gnupg ca-certificates curl software-properties-common
# 导入签名密钥
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit.gpg
# 写入仓库列表（根据发行版自动检测）
distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [arch=amd64 signed-by=/usr/share/keyrings/nvidia-container-toolkit.gpg] https://#' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

3. 安装 nvidia-container-toolkit

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

4. 配置 Docker 默认运行时

sudo nvidia-ctk runtime configure --runtime=docker

该命令会在 /etc/docker/daemon.json 中加入：

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

5. 重启并验证 Docker

sudo systemctl restart docker

6. 功能测试

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

输出应与主机 nvidia-smi 一致，表示 toolkit 工作正常。

7.安装好NVIDIA Container Toolkit后，如何让多个容器使用 GPU

运行命令时指定 GPU：

对于每个需要 GPU 的容器，在 docker run 命令中添加 --gpus 选项。这允许容器访问主机 GPU，而无需额外配置。
示例：假设您有两个容器（一个运行 TensorFlow，另一个运行 PyTorch），可以同时启动它们：
```
# 容器1：使用所有 GPU
docker run --rm --gpus=all your-image1 command1

# 容器2：使用所有 GPU（或指定特定 GPU，如 --gpus device=0）
docker run --rm --gpus=all your-image2 command2
```
- --gpus=all：允许访问主机所有 GPU。
- --gpus device=0：仅访问第一个 GPU（索引从 0 开始）。
- --gpus '"device=0,1"'：访问特定多个 GPU。
多个容器可以同时运行并共享同一个 GPU，资源（如 VRAM、计算核心）会被动态分配。

使用环境变量替代（可选）：

如果不使用 --gpus，可以设置环境变量 NVIDIA_VISIBLE_DEVICES 来控制可见 GPU。
```
docker run --rm -e NVIDIA_VISIBLE_DEVICES=all your-image command
```
- 这与 --gpus=all 等效，但更灵活（如 NVIDIA_VISIBLE_DEVICES=0,1）。
  0

在 Docker Compose 中的配置（如果您使用 Compose 文件管理多个容器）：

在 docker-compose.yml 文件中，为每个服务添加 GPU 配置：

version: '3.8'
services:
  service1:
    image: your-image1
    runtime: nvidia  # 指定 NVIDIA runtime
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              count: all  # 或 device_ids: ['0'] 指定 GPU

  service2:
    image: your-image2
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              count: all

然后运行 docker-compose up。这允许多个服务共享 GPU。

7. 常见问题排查

现象	解决方案
`docker: Error response: unknown runtime nvidia`	重启 Docker 或确认 `daemon.json` 中 “default-runtime” 配置正确
`E: Unable to locate package nvidia-container-toolkit`	NVIDIA APT 源未正确添加或发行版代号不匹配；重新执行仓库配置命令并 `sudo apt-get update` 后再安装
`CUDA driver version is insufficient`	驱动版本低于容器内 CUDA 版本，升级主机驱动或换用匹配版本的 CUDA 镜像
多张 GPU 选择	使用 `--gpus "device=1,2"` 或环境变量 `NVIDIA_VISIBLE_DEVICES`