nvidia-ctk runtime configure: GPUs in Docker

nvidia-ctk runtime configure registers the NVIDIA container runtime with Docker so that docker run --gpus can inject the GPU and driver into containers.

Before a container can see a GPU, the host needs the NVIDIA Container Toolkit configured. nvidia-ctk is the tool that edits the Docker (or containerd) config for you.

What it does

nvidia-ctk runtime configure edits the container runtime configuration (for example /etc/docker/daemon.json) to register the NVIDIA runtime. After a daemon restart, docker run --gpus works because nvidia-container-cli can mount the driver libraries and device nodes into the container.

Common usage

Terminal

# configure Docker to use the NVIDIA runtime, then restart
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
# verify the toolkit can see the GPU
nvidia-container-cli info
# smoke test
docker run --rm --gpus all ubuntu nvidia-smi

Options

Flag	What it does
runtime configure	Wire the NVIDIA runtime into the container engine
--runtime=docker\|containerd\|crio	Which engine to configure
--set-as-default	Make the NVIDIA runtime the default
nvidia-container-cli info	Report GPUs the toolkit can inject
nvidia-container-cli list	List the driver files it would mount

In CI

On a fresh self-hosted runner, run nvidia-ctk runtime configure and restart Docker once during provisioning, then a container job can use --gpus all. If GPU containers fail, nvidia-container-cli info quickly confirms whether the toolkit or the driver is the problem.

Common errors in CI

docker run --gpus all failing with "could not select device driver \"\" with capabilities: [[gpu]]" means the NVIDIA Container Toolkit is not installed or not configured; run nvidia-ctk runtime configure and restart the daemon. "nvidia-container-cli: initialization error: nvml error: driver not loaded" means the host driver itself is missing. "unknown or invalid runtime name: nvidia" means the runtime was never registered in the Docker config.