Docker container can't see GPU — nvidia-container-toolkit missing

docker run --gpus all fails because nvidia-container-toolkit isn't installed (or the Docker daemon wasn't restarted after install). This is the single most common Docker-GPU failure.

1. Install nvidia-container-toolkit (Ubuntu / Debian):

distribution=$(. /etc/os-release; echo $ID$VERSION_ID)
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/$distribution/libnvidia-container.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 update
sudo apt install -y nvidia-container-toolkit

2. Configure Docker runtime + restart daemon:

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3. Verify GPU visible in container:

docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi

4. Docker Compose GPU access:

services:
  vllm:
    image: vllm/vllm-openai:latest
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

5. WSL2 case: the same toolkit install works inside WSL2 with Docker Desktop's WSL2 backend. The Windows-host driver passes through; you only need the toolkit + Docker engine inside WSL2.

Full pattern in the Linux local AI guide.