nvidia-container-toolkit 是让 Docker 容器能够调用宿主机 NVIDIA GPU 的关键组件。由于官方源位于境外，国内用户直接配置官方仓库可能会遇到网络问题。本文提供了三种安装方式，你可根据自己的网络情况选择：
- 官方安装方法（适用于可访问境外网络的环境）
- 国内在线安装方法（推荐，使用中科大镜像源）
- 离线安装方法（当在线方式受阻时使用）
一、官方安装方法
以下步骤适用于 Ubuntu / Debian 系发行版。
1. 安装依赖
sudo apt-get update && sudo apt-get install -y --no-install-recommends \
ca-certificates \
curl \
gnupg2
2. 配置生产仓库
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
3. （可选）启用实验包
sudo sed -i -e '/experimental/ s/^#//g' /etc/apt/sources.list.d/nvidia-container-toolkit.list
4. 更新软件包列表
sudo apt-get update
5. 安装指定版本（以 1.19.1 为例）
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.19.1-1
sudo apt-get install -y \
nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
📖 官方安装指南：https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html
二、国内在线安装方法（推荐，使用中科大镜像源）
如果你无法正常访问 NVIDIA 官方源，可以使用中国科学技术大学（USTC）的镜像源。
1. 安装依赖
sudo apt-get update && sudo apt-get install -y --no-install-recommends \
ca-certificates \
curl \
gnupg2
2. 添加中科大的 GPG 密钥和软件源
curl -fsSL https://mirrors.ustc.edu.cn/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://mirrors.ustc.edu.cn/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
中科大镜像站与上游（NVIDIA GitHub）保持较高的同步频率，服务稳定可靠。
3. 更新软件源并安装
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
4. （可选）安装特定版本
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.19.1-1
sudo apt-get install -y \
nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}
三、离线安装方法（使用 GitHub 下载的 deb 包）
如果网络环境完全无法访问境外资源，可以手动下载 .deb 文件并本地安装。
1. 下载 deb 包
访问 NVIDIA 官方 GitHub 仓库，下载对应架构（通常为 amd64）的四个文件：
-
下载页面：https://github.com/NVIDIA/libnvidia-container/tree/gh-pages/stable/deb/amd64/
-
需要下载的文件（以版本 1.18.2 为例，建议选择与 Docker 版本兼容的稳定版）：
libnvidia-container1_1.18.2-1_amd64.deb
libnvidia-container-tools_1.18.2-1_amd64.deb
nvidia-container-toolkit-base_1.18.2-1_amd64.deb
nvidia-container-toolkit_1.18.2-1_amd64.deb
📦 该版本包含的包信息可参考 Release Notes 1.18.2。
建议将这四个文件放在同一个目录下，例如
~/nvidia-debs/。
2. 安装依赖（可选但推荐）
sudo apt update
sudo apt install -y libseccomp2
3. 按顺序安装 deb 包
⚠️ 注意顺序很重要，后面的包依赖前面的包：
cd ~/nvidia-debs
sudo dpkg -i libnvidia-container1_1.18.2-1_amd64.deb
sudo dpkg -i libnvidia-container-tools_1.18.2-1_amd64.deb
sudo dpkg -i nvidia-container-toolkit-base_1.18.2-1_amd64.deb
sudo dpkg -i nvidia-container-toolkit_1.18.2-1_amd64.deb
4. 修复可能缺失的系统依赖
如果安装过程中提示依赖缺失，运行以下命令自动修复：
sudo apt --fix-broken install -y
四、配置 Docker 运行时（所有方法通用）
安装完成后，无论使用哪种方式，都需要配置 Docker 运行时并重启服务。
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
五、验证安装
运行以下两个测试命令验证 GPU 是否可以被 Docker 正常调用。
测试 1：运行 nvidia-smi
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
成功输出示例：
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.129.03 Driver Version: 535.129.03 CUDA Version: 12.2 |
|-------------------------------+----------------------+----------------------+
...
测试 2：检查 CUDA 编译器版本（可选）
docker run --rm --gpus all nvidia/cuda:12.2.0-devel-ubuntu22.04 nvcc --version
输出应包含类似 Cuda compilation tools, release 12.2 的信息。
六、常见问题及解决方案
| 问题 | 可能原因 | 解决方法 |
|---|---|---|
nvidia-ctk: command not found | toolkit 未正确安装 | 检查 deb 安装顺序，或重新运行在线安装命令 |
failed to discover GPU vendor from CDI | CDI 配置缺失 | 执行 sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml 并重启 docker |
docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]] | 运行时未配置 | 重新执行 sudo nvidia-ctk runtime configure --runtime=docker 并重启 docker |
| 拉取测试镜像时卡住或失败 | 网络问题 | 配置 Docker 镜像加速器（见附录） |
附录：配置 Docker 镜像加速器
如果拉取 nvidia/cuda 测试镜像时速度很慢，可以配置 Docker Hub 镜像加速：
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<-'EOF'
{
"registry-mirrors": [
"https://docker.m.daocloud.io",
"https://docker.xuanyuan.me"
]
}
EOF
sudo systemctl restart docker
评论