docker run --gpus all: Run a GPU Container
docker run --gpus all runs a container with access to every host GPU, injecting the driver and device nodes via the NVIDIA Container Toolkit.
Getting a GPU into a container is a two-part story: the host must have the NVIDIA Container Toolkit configured, and the run must request the GPU with --gpus.
What it does
docker run --gpus tells Docker (through the NVIDIA runtime) to expose host GPUs to the container. --gpus all exposes every GPU; you can also request a count or specific device UUIDs/indices. The image needs matching CUDA runtime libraries; the driver comes from the host.
Common usage
# all GPUs, quick smoke test
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
# just 2 GPUs
docker run --rm --gpus 2 my-image
# specific GPUs by index
docker run --rm --gpus '"device=0,1"' my-imageOptions
| Flag | What it does |
|---|---|
| --gpus all | Expose every host GPU |
| --gpus <N> | Expose N GPUs |
| --gpus '"device=0,1"' | Expose specific GPUs by index or UUID |
| -e NVIDIA_VISIBLE_DEVICES | Alternative device selection via env var |
| --runtime=nvidia | Legacy explicit runtime (usually not needed now) |
In CI
Verify GPU access inside the container early with a throwaway nvidia-smi run before starting the real workload. The container CUDA runtime must be compatible with the host driver; use an official nvidia/cuda base image tag whose CUDA version the host driver supports.
Common errors in CI
"docker: Error response from daemon: could not select device driver \"\" with capabilities: [[gpu]]." means the NVIDIA Container Toolkit is missing or Docker is not configured for it; install it and run nvidia-ctk runtime configure. "Failed to initialize NVML: Unknown Error" inside the container often means the host driver changed under a running container, or cgroup device rules block access. "unknown flag: --gpus" means a Docker older than 19.03.