Docker容器GPU直通nvidia‑container‑

Docker 容器想直接调用 NVIDIA 显卡，
不需要在容器里装驱动，
只要宿主机装好驱动，
并安装 nvidia-container-toolkit 把 GPU 运行时暴露给容器即可。 本文按零基础也能照做的顺序，
讲清从环境检查到部署验证，
以及高频报错的解决方法。

部署前先确认三件事

在安装之前，先在宿主机执行下面两条命令：

nvidia-smi
docker --version

nvidia-smi 能正常显示显卡型号和驱动版本，说明驱动已就绪。
如果提示命令不存在，需要先安装 NVIDIA 驱动。
Docker 建议 19.03 以上版本，因为 --gpus 参数从该版本开始原生支持。
确认这两点后，再继续安装 toolkit。

安装 nvidia-container-toolkit

以 Ubuntu/Debian 为例，通过官方仓库安装：

curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

CentOS/RHEL 用户把源地址换成 stable/rpm 对应配置，
再用 yum install nvidia-container-toolkit 即可，
具体地址以 NVIDIA 官方仓库说明为准。

安装完成后，需要把 NVIDIA 运行时注册给 Docker：

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

这一步会修改 Docker 的 daemon 配置，让 Docker 能识别 GPU 设备。

容器内调用 GPU 的验证方法

执行下面命令拉取一个自带 nvidia-smi 的测试镜像并运行：

docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu20.04 nvidia-smi

如果输出和宿主机 nvidia-smi 类似，能看到 GPU 型号和显存，说明 Docker 容器 GPU 直通已经成功。
之后运行你的 CUDA 应用时，只要在 docker run 后面加上 --gpus all 即可。

如果不想给全部 GPU，可以用：

docker run --rm --gpus '"device=0"' nvidia/cuda:11.8.0-base-ubuntu20.04 nvidia-smi

高频报错与避坑说明

遇到 could not select device driver "" with capabilities: [[gpu]]，通常是 Docker 没有识别到 NVIDIA runtime。
重新执行 sudo nvidia-ctk runtime configure --runtime=docker 然后重启 Docker，如果仍不行，检查 /etc/docker/daemon.json 中是否包含 "runtimes": {"nvidia"} 配置。

容器内提示 nvidia-smi not found，说明镜像本身没带 NVIDIA 工具，换用带 CUDA 的基础镜像，而不是在容器里安装驱动。

宿主机驱动正常但容器拿不到 GPU，先检查内核模块是否加载：

lsmod | grep nvidia

如果为空，执行 modprobe nvidia，并确认 Docker 服务在驱动加载后重启。

避坑重点：不要在容器内部安装 NVIDIA 驱动，宿主机驱动会通过 toolkit 映射进容器，重复安装容易导致版本冲突。
另外，重启宿主机后需要确认 Docker 服务已启动，否则容器可能无法识别 GPU。

如果你正在处理 Docker 容器 GPU 直通的部署问题，建议严格按本文顺序操作一遍，再根据实际报错定位。
只要驱动、toolkit、runtime 三者匹配，容器内调用显卡就是一条命令的事。