上一篇 《如何在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.xx | CUDA 12.0 |
| 535.xx | CUDA 12.2 |
| 550.xx | CUDA 12.4 |
| 560.xx | CUDA 12.6 |
| 570.xx | CUDA 12.8 |
| 580.xx | CUDA 13.0 |
不用死记这张表,装之前在宿主机上跑一次 nvidia-smi 就能看到答案:
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 已按第一篇的方法装好。
第一步:添加官方仓库
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 源地址。
第二步:安装软件包
sudo apt-get updatesudo apt-get install -y nvidia-container-toolkit验证点:装完后这两个命令能找到就对了:
which nvidia-ctk nvidia-container-runtime第三步:把 NVIDIA 运行时注册进 Docker
这是最容易漏掉、漏掉就必报错的一步。用官方的 nvidia-ctk 工具自动改 Docker 的配置:
sudo nvidia-ctk runtime configure --runtime=docker它会往 /etc/docker/daemon.json 里写入 NVIDIA 运行时的定义。可以打开确认一眼:
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 使配置生效
sudo systemctl restart docker验证点:docker info | grep -i runtime 的输出里能看到 nvidia 字样,说明运行时注册成功。注意重启 Docker 会重启所有设置了重启策略的容器,生产机上请挑低峰期操作。
docker run 调用 GPU
配置生效后,给 docker run 加一个 --gpus 参数就能把显卡交给容器。
全部显卡都给容器
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 后第一时间跑,它是最快的端到端验证。
只给指定的卡
多卡机器(或者只想留一张卡给宿主机上的其他任务)可以按编号分配,注意引号不能省:
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 能算:
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,然后进容器验证:
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 的能力项各管一摊事,按需开,别无脑全开:
| 能力项 | 管什么 | 谁需要它 |
|---|---|---|
compute | CUDA 计算、cuDNN 等计算库 | 所有 AI / 科学计算场景,必备 |
utility | nvidia-smi 等管理查询工具 | 想在容器里查显卡状态时 |
video | NVENC / NVDEC 硬件编解码 | FFmpeg 转码、Jellyfin 等媒体服务 |
graphics | OpenGL / 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:
nvidia-smi进程列表里显示的是容器内进程在宿主机上的 PID 和显存占用,把 PID 拿去 docker top <容器名> 或者 docker inspect 里对照,就能定位到具体是哪个容器。想持续盯着看可以用:
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 链路没通的标志性错误,按顺序查:
- 宿主机
nvidia-smi是否正常——宿主机都不行,容器免谈; nvidia-container-toolkit装了没有:dpkg -l | grep nvidia-container-toolkit;nvidia-ctk runtime configure --runtime=docker执行过没有,daemon.json里有没有runtimes.nvidia;- 配置之后重启过 Docker 没有——改完配置不重启是最常见的乌龙;
- 用的还是不是老写法:
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 段冲掉。重新执行一遍:
sudo nvidia-ctk runtime configure --runtime=dockersudo systemctl restart dockerdocker 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 或具体编号覆盖掉,是最快的验证办法。
设备节点与权限检查
怀疑注入本身没发生时,直接看设备节点。宿主机上应该有这些文件:
ls -l /dev/nvidia*能看到 nvidia0(每张卡一个)、nvidiactl、nvidia-uvm、nvidia-modeset 才算驱动加载正常;连宿主机都没有这些节点,是驱动层的问题,先修驱动。再看容器里:
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、内存一样成了可编排的资源:想给哪个服务、给几张卡、什么时候收回,都是一行配置的事。