Docker "--gpus" - "could not select device driver" / Flag Not Supported in CI

docker run --gpus needs the NVIDIA Container Toolkit registered with the daemon and an actual GPU on the host. Without the toolkit Docker cannot select a GPU device driver; on a runner with no GPU the flag has nothing to attach.

What this error means

A docker run --gpus all ... fails with could not select device driver "" with capabilities: [[gpu]], or an older Docker errors with unknown flag: --gpus. The same image runs fine without the GPU flag.

docker run output

docker: Error response from daemon: could not select device driver "" with
capabilities: [[gpu]].
# or, on old Docker: unknown flag: --gpus

Common causes

NVIDIA Container Toolkit not installed/registered

The --gpus flag relies on the NVIDIA Container Toolkit runtime hook. Without it installed and the daemon configured, Docker has no GPU device driver to select.

The runner has no GPU

A standard CI runner has no NVIDIA GPU, so there is no device for --gpus to expose even if the flag is recognized.

Docker too old to support --gpus

Very old Docker versions predate the --gpus flag and report it as unknown.

How to fix it

Install and configure the NVIDIA Container Toolkit

Install the toolkit and register the runtime, then verify GPU access.

Terminal

# install the toolkit, then:
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

Run on a GPU runner, or drop the flag

Use a GPU-equipped runner for jobs that need --gpus.
For CPU-only CI, remove --gpus and run the CPU code path.
Upgrade Docker if --gpus is reported as an unknown flag.

How to prevent it

Install the NVIDIA Container Toolkit on GPU runners and register the runtime.
Only pass --gpus where a GPU and toolkit are present.
Keep Docker current so the flag is supported.