容器无法访问gpu的根本原因是宿主机缺少nvidia container toolkit等运行时组件，需先确保nvidia-smi正常输出、驱动模块加载，再安装配置toolkit并设为docker默认runtime，最后启动时显式使用--gpus参数。
容器无法访问 gpu，不是镜像或容器概念本身的问题，而是运行时环境缺失关键组件。镜像只是静态的打包文件，不包含驱动；容器是运行实例，但默认完全隔离硬件设备——gpu 就在被隔离之列。要让容器用上 gpu，必须在宿主机上补全“透传链路”，而不是修改镜像或重写容器。
确认宿主机 GPU 基础就绪
这是所有后续操作的前提。如果这一步失败，后面全无意义：
- 运行 nvidia-smi，必须能正常显示 GPU 型号、温度、驱动版本（建议 ≥ 550）
- 运行 lsmod | grep nvidia，应看到 nvidia、nvidia_uvm、nvidia_drm 等模块已加载
- 若 nvidia-smi 报错，先重装驱动，不要跳过这步
安装并配置 NVIDIA Container Toolkit
这是现代 Docker（≥19.03）访问 GPU 的标准方案，替代已废弃的 nvidia-docker2：
- 添加 NVIDIA 官方源并安装工具包（以 Ubuntu/Debian 为例）：
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
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit nvidia-container-runtime - 配置 Docker 使用 NVIDIA 运行时：
sudo nvidia-ctk runtime configure --runtime=docker --set-as-default
验证配置并排查常见陷阱
配置完成后，必须验证是否真正生效：
- 重启服务：sudo systemctl restart docker
- 运行验证命令：sudo docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi
若输出中显示 Tesla T4、A100、K100 或你的真实 GPU 型号，说明成功 - 若仍报 "could not select device driver"，检查 /etc/docker/daemon.json 是否含重复或冲突配置；若用 Snap 安装 Docker，必须卸载并改用官方 .deb 包
- 若容器内 nvidia-smi 显示 "Failed to initialize NVML: Unknown Error"，大概率是宿主机执行了 systemctl daemon-reload 导致 GPU 设备引用丢失，可尝试重启 docker 或在 daemon.json 中加 "exec-opts": ["native.cgroupdriver=cgroupfs"]
运行容器时显式启用 GPU
即使环境配好，也必须在启动时声明，Docker 不会自动透传 GPU：
- 暴露全部 GPU：docker run --gpus all your-image
- 指定某张卡：docker run --gpus device=0,2 your-image
- 限制内存（需驱动支持）：docker run --gpus '"device=0,capabilities=compute,utility"' --shm-size=1g your-image
- 避免使用 --privileged=true 替代 GPU 配置，它不解决根本问题，且带来安全风险
