How to fix Error response from daemon: Unknown runtime specified nvidia in Docker

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 210 views

This error occurs when Docker cannot find the NVIDIA container runtime. It typically means the nvidia-container-toolkit is not installed, Docker's daemon.json is not configured correctly, or Docker needs to be restarted after installation.

Quick fix

Fixes Error response from daemon: Unknown runtime specified nvidia

docker info | grep -i runtime
  1. Check if NVIDIA runtime is available
  2. Install the NVIDIA Container Toolkit
  3. Configure Docker to use the NVIDIA runtime
  4. Restart the Docker daemon
docker — error
docker info | grep -i runtime
Error response from daemon: Unknown runtime specified nvidia

What this error means

When you try to run a Docker container with `--runtime=nvidia` or use GPU acceleration, Docker looks for the NVIDIA runtime in its configuration. This runtime acts as a bridge between Docker and your NVIDIA GPU drivers, allowing containers to access GPU resources. The "Unknown runtime specified nvidia" error indicates that Docker doesn't recognize "nvidia" as a valid runtime. This happens because: 1. The NVIDIA Container Toolkit (which includes `nvidia-container-runtime`) is not installed 2. Docker's daemon.json configuration doesn't include the nvidia runtime entry 3. Docker daemon hasn't been restarted after installing the toolkit 4. The runtime binary path is incorrect in the configuration

Typical symptoms

  • Running containers with --runtime=nvidia fails immediately
  • Docker Compose files with 'runtime: nvidia' fail to start services
  • GPU-accelerated containers (CUDA, TensorFlow GPU) won't launch
  • Error message appears before container creation begins
  • The same container runs fine without the --runtime=nvidia flag

Common causes

  1. nvidia-container-toolkit is not installed on the host system
  2. Docker daemon.json is missing the nvidia runtime configuration
  3. Docker daemon was not restarted after installing the toolkit
  4. Using --runtime=nvidia on Docker 19.03+ instead of --gpus flag
  5. nvidia-container-runtime binary is not in the expected path
  6. Conflicting Docker runtime configurations

How to fix "Error response from daemon: Unknown runtime specified nvidia"

1Check if NVIDIA runtime is available

First, verify what runtimes Docker currently knows about:

bash
docker info | grep -i runtime

If you see only Runtimes: runc (without nvidia), the NVIDIA runtime is not configured. If nvidia is listed but still failing, the configuration may be incorrect.

2Install the NVIDIA Container Toolkit

Install the NVIDIA Container Toolkit which provides the nvidia-container-runtime:

For Ubuntu/Debian:

bash
# Add the NVIDIA GPG key
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

# Add the repository
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

# Install the toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

For RHEL/CentOS:

bash
curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | \
  sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo

sudo yum install -y nvidia-container-toolkit
3Configure Docker to use the NVIDIA runtime

Use the nvidia-ctk tool to automatically configure Docker:

bash
sudo nvidia-ctk runtime configure --runtime=docker

This command modifies /etc/docker/daemon.json to include the nvidia runtime. You can verify the configuration:

bash
cat /etc/docker/daemon.json

You should see something like:

json
{
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
4Restart the Docker daemon

Apply the configuration changes by restarting Docker:

bash
sudo systemctl restart docker

Alternatively, you can send a SIGHUP signal:

bash
sudo pkill -SIGHUP dockerd

Verify the runtime is now available:

bash
docker info | grep -i runtime
# Should show: Runtimes: nvidia runc
5Test GPU access in a container

Verify everything works by running a test container:

bash
# Using the new --gpus flag (recommended for Docker 19.03+)
docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

# Or using the legacy --runtime=nvidia flag
docker run --rm --runtime=nvidia nvidia/cuda:12.0-base nvidia-smi

You should see the output of nvidia-smi showing your GPU(s).

Advanced notes

## Using --gpus instead of --runtime=nvidia

Starting with Docker 19.03, the recommended approach is to use --gpus instead of --runtime=nvidia:

bash
# Access all GPUs
docker run --gpus all nvidia/cuda:12.0-base nvidia-smi

# Access specific GPUs by index
docker run --gpus '"device=0,1"' nvidia/cuda:12.0-base nvidia-smi

# Access specific GPU by UUID
docker run --gpus '"device=GPU-xxxxx"' nvidia/cuda:12.0-base nvidia-smi

The --gpus flag works even without the runtimes section in daemon.json, as long as the nvidia-container-toolkit is installed.

## Docker Compose Configuration

For Docker Compose (version 2.x or later), use the deploy section:

yaml
services:
  gpu-service:
    image: nvidia/cuda:12.0-base
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

## WSL2 Considerations

On Windows with WSL2, the NVIDIA drivers are installed on the Windows side, but you still need the nvidia-container-toolkit inside WSL:

bash
# In WSL2, verify NVIDIA driver is accessible
nvidia-smi

# Then install the toolkit as normal
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

## Troubleshooting Tips

- If nvidia-container-runtime is not found, verify installation: which nvidia-container-runtime
- Check for conflicting configurations in ~/.docker/daemon.json vs /etc/docker/daemon.json
- On some systems, you may need to enable the nvidia-persistenced service

Frequently asked questions

What does "Error response from daemon: Unknown runtime specified nvidia" mean?
When you try to run a Docker container with --runtime=nvidia or use GPU acceleration, Docker looks for the NVIDIA runtime in its configuration. This runtime acts as a bridge between Docker and your NVIDIA GPU drivers, allowing containers to access GPU resources. The "Unknown runtime specified nvidia" error indicates that Docker doesn't recognize "nvidia" as a valid runtime.
How do I fix "Error response from daemon: Unknown runtime specified nvidia"?
This error occurs when Docker cannot find the NVIDIA container runtime. It typically means the nvidia-container-toolkit is not installed, Docker's daemon.json is not configured correctly, or Docker needs to be restarted after installation.
What causes "Error response from daemon: Unknown runtime specified nvidia"?
nvidia-container-toolkit is not installed on the host system Docker daemon.json is missing the nvidia runtime configuration Docker daemon was not restarted after installing the toolkit
Is the "Error response from daemon: Unknown runtime specified nvidia" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading