4195 字
21 分钟
GPU 容器实战:NVIDIA Container Toolkit
2026-11-15

上一篇 《如何在Linux部署Docker&Compose》 把 Docker 的地基打好了,容器跑起来没问题。但只要你的业务沾上 AI 推理、视频转码、生图,就会撞上一个新问题:容器里默认根本看不见显卡。宿主机上明明插着一张 NVIDIA GPU,nvidia-smi 在宿主机跑得好好的,一进容器就报找不到设备。

这篇就把这条路彻底打通:先讲清容器为什么默认用不了 GPU、NVIDIA Container Toolkit 在中间扮演什么角色,再一步步走完安装、docker run 与 Compose 两种调用写法、环境变量调优,最后是排障。走完这一篇,你的容器就能像宿主机进程一样直接调用显卡了。

先搞清楚:容器为什么默认用不了 GPU#

普通容器能直接用的硬件其实非常有限:CPU、内存、磁盘、网络,这些都是内核原生支持隔离和分配的。但 GPU 不一样,它没有进 Linux 内核的统一抽象层,应用程序要通过 NVIDIA 的闭源驱动和一整套用户态库(CUDA 运行库、libnvidia-ml 等)才能跟显卡对话。

容器与宿主机共享同一个内核,但文件系统是隔离的。容器镜像里通常只有应用自己带的那点东西,既没有宿主机的驱动库,也没有 /dev/nvidia0、/dev/nvidiactl 这些设备节点的访问通道。所以默认状态下,容器里的程序去找显卡,只会一无所获。

NVIDIA Container Toolkit 解决的就是这个问题。它的工作方式可以概括为三件事:

环节做了什么
运行时钩子容器启动前,nvidia-container-runtime 拦截创建流程,在容器真正跑起来之前先做注入
设备注入把 /dev/nvidia0、/dev/nvidia-uvm 等设备节点映射进容器
驱动库注入把宿主机上的驱动用户态库(如 libcuda.so、libnvidia-ml.so)挂载进容器

这里有个关键认知,整篇的坑基本都从它派生出来:

驱动永远在宿主机,容器里只需要 CUDA 运行库。

也就是说,你不需要、也不应该在容器镜像里装 NVIDIA 驱动。镜像里只需要带上应用依赖的 CUDA 运行库(比如 PyTorch 镜像自带的 CUDA 版本),真正的驱动由 Toolkit 在运行时从宿主机注入。这也是为什么官方 CUDA 镜像(如 nvidia/cuda:12.4.1-base-ubuntu22.04)体积不大、且能在不同驱动的机器上跑——前提是宿主机驱动足够新,这就是下一节的版本对应关系。

版本对应关系:驱动决定 CUDA 上限#

注入机制带来一条硬性约束:容器里用的 CUDA 版本,不能高于宿主机驱动支持的 CUDA 上限。驱动太旧、镜像太新,容器一调用 CUDA 就会报错(最典型的就是后面排障里要讲的 Driver/library version mismatch)。

宿主机驱动与可支持的最高 CUDA 版本大致对应如下(Linux x86_64):

宿主机驱动版本最高支持的 CUDA 版本
470.xx(Kepler 末代)CUDA 11.4
525.xxCUDA 12.0
535.xxCUDA 12.2
550.xxCUDA 12.4
560.xxCUDA 12.6
570.xxCUDA 12.8
580.xxCUDA 13.0

不用死记这张表,装之前在宿主机上跑一次 nvidia-smi 就能看到答案:

Terminal window
nvidia-smi

输出右上角有一行 CUDA Version: 12.4,注意它的含义是「这台机器的驱动最高支持到 CUDA 12.4」,不是你装了 CUDA 12.4。选容器镜像时,镜像标签里的 CUDA 版本小于等于这个数就安全;大于它,先升级宿主机驱动再说。

WARNING

宿主机还没装 NVIDIA 驱动的话,先把驱动装好再谈容器。Debian/Ubuntu 上推荐用发行版仓库的驱动包(如 nvidia-driver 元包或 Software & Updates 里的专有驱动),不要去官网下载 .run 文件手动装——手动装的驱动每次内核升级都要重装一遍,内核一升级驱动就失效是新手最常见的翻车点。驱动装完务必重启一次,并在宿主机确认 nvidia-smi 能正常输出显卡信息,再继续下面的步骤。

安装 NVIDIA Container Toolkit#

以下流程适用于 Debian / Ubuntu,装的是 NVIDIA 官方仓库的 nvidia-container-toolkit 包。前置条件:宿主机驱动已装好、nvidia-smi 正常、Docker 已按第一篇的方法装好。

第一步:添加官方仓库#

Terminal window
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

验证点:/etc/apt/sources.list.d/nvidia-container-toolkit.list 文件存在,内容是一行带 signed-by 的 deb 源地址。

第二步:安装软件包#

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

验证点:装完后这两个命令能找到就对了:

Terminal window
which nvidia-ctk nvidia-container-runtime

第三步:把 NVIDIA 运行时注册进 Docker#

这是最容易漏掉、漏掉就必报错的一步。用官方的 nvidia-ctk 工具自动改 Docker 的配置:

Terminal window
sudo nvidia-ctk runtime configure --runtime=docker

它会往 /etc/docker/daemon.json 里写入 NVIDIA 运行时的定义。可以打开确认一眼:

Terminal window
cat /etc/docker/daemon.json

应该能看到类似内容(你原有的其他配置会被保留合并):

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

nvidia-ctk runtime configure 是覆盖式合并:它会重写 daemon.json 里 runtimes 这一段。如果你之前手写过其他运行时配置,改完要通读一遍整个文件再重启。另外,不要再手工往 daemon.json 里加已经过时的 default-runtime 写法——老教程里常见的 "default-runtime": "nvidia" 是 nvidia-docker 时代的产物,现在既没必要也会让所有容器都强行走 GPU 注入,普通容器反而容易出问题。

第四步:重启 Docker 使配置生效#

Terminal window
sudo systemctl restart docker

验证点:docker info | grep -i runtime 的输出里能看到 nvidia 字样,说明运行时注册成功。注意重启 Docker 会重启所有设置了重启策略的容器,生产机上请挑低峰期操作。

docker run 调用 GPU#

配置生效后,给 docker run 加一个 --gpus 参数就能把显卡交给容器。

全部显卡都给容器#

Terminal window
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

注意选镜像版本时对照第二节的表:我这里宿主机驱动支持到 CUDA 12.4,所以选了 12.4.1 的镜像。如果一切正常,输出就是熟悉的 nvidia-smi 表格:显卡型号、驱动版本、显存占用(0MiB)整整齐齐——在容器里看到这张表,就等于整条链路全部打通了。这个命令建议你装完 Toolkit 后第一时间跑,它是最快的端到端验证。

只给指定的卡#

多卡机器(或者只想留一张卡给宿主机上的其他任务)可以按编号分配,注意引号不能省:

Terminal window
docker run --rm --gpus '"device=0"' nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

多张一起给用逗号:--gpus '"device=0,1"'。编号就是宿主机 nvidia-smi 里左边的 GPU 序号(0 起)。容器里看到的显卡会被重新从 0 编号,不用奇怪。

--gpus 还支持按数量给,比如 --gpus 1 表示随便分配一张。生产环境更推荐写死 device= 编号,行为可预期,排障时也清楚哪张卡归谁。

一个最小的实用例子#

光看 nvidia-smi 不过瘾的话,可以跑一个真正的计算镜像确认 CUDA 能算:

Terminal window
docker run --rm --gpus all nvidia/cuda:12.4.1-sample-ubuntu22.04 vectorAdd

(示例镜像的标签各 CUDA 版本略有差异,拉不到时换 nvidia/cuda:12.4.1-devel-ubuntu22.04 里自带的示例同理。)输出最后出现 Test PASSED 就说明不只是「看得见」,而是真的能算。

Compose 写法:把 GPU 写进编排文件#

实际项目都是用 Compose 管理的,GPU 分配写在服务的 deploy.resources.reservations.devices 段里:

services:
ollama:
image: ollama/ollama:latest
container_name: ollama
restart: unless-stopped
ports:
- "11434:11434"
volumes:
- ./ollama-data:/root/.ollama
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]

几个字段逐个说清:

字段含义
driver: nvidia用哪个设备的驱动框架,NVIDIA 显卡固定写 nvidia
count: all分配几张卡,all 是全部,也可以写数字如 count: 1
device_ids: ['0']指定卡编号,与 count 二选一,不能同时写
capabilities: [gpu]声明需要的设备能力,GPU 计算固定要带 gpu

只给一张指定卡的写法:

deploy:
resources:
reservations:
devices:
- driver: nvidia
device_ids: ['0']
capabilities: [gpu]
WARNING

网上很多老文章在 Compose 里写 runtime: nvidia,那是 Docker Compose v1 加 nvidia-docker2 时代的写法。现在 Compose v2 已经不再认 runtime 字段指定 GPU,照抄老配置的结果是显卡压根没分配进去,程序只能用 CPU 跑,还不报错、特别难查。认准 deploy.resources.reservations.devices 这一套新写法。顺带说一句:deploy 段在 Swarm 里是编排参数,但在普通 docker compose up 下,resources.reservations.devices 这部分是生效的,不用担心被忽略。

改完配置照常 docker compose up -d,然后进容器验证:

Terminal window
docker compose exec ollama nvidia-smi

有些精简镜像里没有 nvidia-smi 这个命令,可以换成看设备节点:docker compose exec ollama ls /dev/nvidia*,能列出 nvidia0、nvidiactl 等节点即说明注入成功。

环境变量精调#

--gpus 和 Compose 的 devices 段决定「给不给、给哪张」,还有两个环境变量决定「给了之后怎么用」,出问题时经常要动它们:

环境变量作用常用取值
NVIDIA_VISIBLE_DEVICES限定容器能看到哪几张卡all(默认)、0、0,1、none(不给卡)、void(给驱动但不给设备)
NVIDIA_DRIVER_CAPABILITIES开放驱动的哪些能力组compute、utility、graphics、video、display,多个用逗号连

NVIDIA_DRIVER_CAPABILITIES 的能力项各管一摊事,按需开,别无脑全开:

能力项管什么谁需要它
computeCUDA 计算、cuDNN 等计算库所有 AI / 科学计算场景,必备
utilitynvidia-smi 等管理查询工具想在容器里查显卡状态时
videoNVENC / NVDEC 硬件编解码FFmpeg 转码、Jellyfin 等媒体服务
graphicsOpenGL / Vulkan 图形渲染图形渲染、部分生图与游戏串流场景
display显示输出相关库容器直接接显示器输出时,服务器场景基本用不上

举个例子,一个纯转码的 FFmpeg 容器这样写就够了,计算能力也可以顺手带上:

environment:
- NVIDIA_VISIBLE_DEVICES=all
- NVIDIA_DRIVER_CAPABILITIES=compute,video,utility

而跑大模型推理的容器通常只需要 compute,utility。能力开得越少,注入的库越少,镜像行为越干净,排障面也越小。默认值是 compute,utility,所以很多镜像什么都不写也能跑——因为它们正好只需要这两项;一旦你的场景涉及转码而又没开 video,就会出现「显卡看得见但 NVENC 用不了」的怪问题,先查这里。

典型场景速配#

把上面的写法套到常见服务上,基本都是十分钟的事:

  • AI 推理(Ollama 等):用上面 Compose 例子的结构,count: all + 默认能力即可。Ollama 官方镜像自带 CUDA 运行库,GPU 分配进去后日志里会出现 inference compute 并识别出显卡型号;如果日志显示走的是 CPU,九成是 devices 段没生效或驱动版本不够。
  • 硬件转码(Jellyfin / FFmpeg):关键是给足 NVIDIA_DRIVER_CAPABILITIES=compute,video,utility,然后在 Jellyfin 后台的播放设置里把硬件加速选成 NVIDIA NVENC。FFmpeg 场景用带 CUDA 的镜像,编码时指定 -hwaccel cuda -c:v h264_nvenc 这类参数。
  • 生图(Stable Diffusion 类):这类镜像基本基于 PyTorch,镜像自带 CUDA,宿主机只管驱动够新。分配写法同推理场景,另外显存是硬约束,nvidia-smi 先确认显存够不够模型用,不够就换小模型或开低显存模式,容器化解决不了显存不足。

运维补充:盯住显存占用#

GPU 分给容器之后,日常最常问的问题是「哪个容器吃了多少显存」。先说一个反直觉的事实:docker stats 不显示 GPU 数据,它只有 CPU、内存、网络和磁盘四类。看 GPU 还是得回到宿主机的 nvidia-smi:

Terminal window
nvidia-smi

进程列表里显示的是容器内进程在宿主机上的 PID 和显存占用,把 PID 拿去 docker top <容器名> 或者 docker inspect 里对照,就能定位到具体是哪个容器。想持续盯着看可以用:

Terminal window
nvidia-smi dmon -s u

它会滚动输出每张卡的算力利用率、显存利用率和功耗,排查「某个服务把卡占满、其他服务排队」时很直观。

还有一个经常被问的点:能不能像限制内存那样,给某个容器限死显存上限? 标准 Docker 加 Toolkit 的组合里没有这个原生参数——GPU 的分配粒度就是「整张卡给或不给」,--gpus 只能选卡和选数量。真要做显存级切分,得上数据中心卡才支持的 MIG(Multi-Instance GPU,把一张物理卡切成多个硬件隔离的实例,再用 device 指定 MIG 实例分配),或者在应用层自己控制(比如 PyTorch 里设 per_process_gpu_memory_fraction)。普通单卡家用和中小服务器场景,按服务分卡、错峰使用就够了,不要在这上面钻牛角尖。

排障#

docker: Error response from daemon: could not select device driver#

完整报错一般是 could not select device driver "nvidia" with capabilities: [[gpu]]。这是 Toolkit 链路没通的标志性错误,按顺序查:

  1. 宿主机 nvidia-smi 是否正常——宿主机都不行,容器免谈;
  2. nvidia-container-toolkit 装了没有:dpkg -l | grep nvidia-container-toolkit;
  3. nvidia-ctk runtime configure --runtime=docker 执行过没有,daemon.json 里有没有 runtimes.nvidia;
  4. 配置之后重启过 Docker 没有——改完配置不重启是最常见的乌龙;
  5. 用的还是不是老写法:docker run 漏了 --gpus,或 Compose 还在写 runtime: nvidia。

容器里 nvidia-smi 报 Driver/library version mismatch#

全称 Failed to initialize NVML: Driver/library version mismatch。意思是容器里被注入的用户态驱动库版本和宿主机内核驱动对不上。常见诱因:

  • 宿主机刚升级了驱动但没重启,内核里跑的还是旧驱动模块,而磁盘上的库已经是新版——重启宿主机即可;
  • 容器镜像的 CUDA 版本超过了驱动上限(回到第二节对照表,换低版本镜像或升级驱动);
  • 宿主机驱动是 .run 文件手动装的,发行版包又装了一份,库文件混杂——清理成只保留一种安装方式。

重启 Docker 后 GPU 丢失#

之前好好的,一次 systemctl restart docker 或系统更新后 --gpus 又报错。优先怀疑 daemon.json 被改动:某些工具或手工编辑会把 runtimes 段冲掉。重新执行一遍:

Terminal window
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

最后一条验证命令能过,就说明链路恢复。

程序报 CUDA error: no device / 容器里看不到卡#

nvidia-smi 在容器里能跑、但应用说找不到 GPU,或者反过来应用能跑但你想确认它到底用了哪张卡,先查环境变量:是不是某个环节把 NVIDIA_VISIBLE_DEVICES 设成了 none 或 void(有些基础镜像或上层编排会带这个变量),再查 Compose 的 devices 段 count 是否写了 0。把变量显式写成 NVIDIA_VISIBLE_DEVICES=all 或具体编号覆盖掉,是最快的验证办法。

设备节点与权限检查#

怀疑注入本身没发生时,直接看设备节点。宿主机上应该有这些文件:

Terminal window
ls -l /dev/nvidia*

能看到 nvidia0(每张卡一个)、nvidiactl、nvidia-uvm、nvidia-modeset 才算驱动加载正常;连宿主机都没有这些节点,是驱动层的问题,先修驱动。再看容器里:

Terminal window
docker run --rm --gpus all --entrypoint ls nvidia/cuda:12.4.1-base-ubuntu22.04 -l /dev/nvidia*

容器里缺节点而宿主机有,就是 Toolkit 注入环节的问题,回到前两条排查。

WARNING

不要用给容器加 --privileged 或者把 /dev 整个挂进去的方式来「解决」GPU 不可见的问题。这样做等于把宿主机的全部设备权限都交给容器,安全边界荡然无存,而且掩盖了真正的配置错误。Toolkit 的注入是精准映射,装好配好之后根本不需要特权模式。

小结#

  • 容器用不了 GPU 是因为驱动和设备节点被隔离在外,NVIDIA Container Toolkit 在容器启动时把宿主机的驱动库和设备精准注入进来;容器镜像只带 CUDA 运行库,永远不装驱动。
  • 版本红线只有一条:容器镜像的 CUDA 版本 ≤ 宿主机 nvidia-smi 右上角显示的 CUDA 上限。
  • 安装四步:加官方仓库 → 装 nvidia-container-toolkit → nvidia-ctk runtime configure --runtime=docker → 重启 Docker,缺一不可。
  • 调用写法:docker run 用 --gpus all 或 --gpus '"device=0"';Compose 用 deploy.resources.reservations.devices,别再抄 runtime: nvidia 的老写法。
  • 精调靠两个环境变量:NVIDIA_VISIBLE_DEVICES 管给哪张卡,NVIDIA_DRIVER_CAPABILITIES 管开哪些能力,转码记得开 video。
  • 排障先分层:宿主机 nvidia-smi → Toolkit 与 daemon.json → 容器内验证,一层层缩小范围,别一上来就重装。

链路打通之后,GPU 在 Docker 里就和 CPU、内存一样成了可编排的资源:想给哪个服务、给几张卡、什么时候收回,都是一行配置的事。

GPU 容器实战:NVIDIA Container Toolkit
https://www.anexns.cloudns.org/posts/docker-gpu-nvidia/
作者
Anexns
发布于
2026-11-15
许可协议
CC BY-NC-SA 4.0