Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Vulkan finds no NVIDIA GPU inside a Docker container

Errornvidia-smi lists the GPU in the container, but a Vulkan program finds no NVIDIA device

Short answer

By default the NVIDIA Container Toolkit gives a container only the utility and compute capabilities. Vulkan needs graphics. Set NVIDIA_DRIVER_CAPABILITIES to include graphics and utility, make sure the right GPU is visible, and confirm the Docker runtime is configured for the toolkit.

  • Applies to NVIDIA Container Toolkit 1.1x, Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check which capabilities the container has. If the variable is empty, you are on the default of utility and compute, which has no Vulkan.

    docker run --rm --gpus all ubuntu sh -c 'echo caps=$NVIDIA_DRIVER_CAPABILITIES; nvidia-smi -L'
  2. 2Match what you see, then jump to its fix

    1. 1nvidia-smi works, Vulkan or OpenGL fails; the variable is emptyThe graphics capability is not enabledFix
    2. 2An X11 or Wayland app needs a window as well as VulkanThe container shows windows but only compute was requestedFix
    3. 3Several GPUs on the host; Vulkan shows none or the wrong oneThe wrong GPU is assigned to the containerFix
    4. 4--runtime=nvidia is rejected, or no GPU appears at allDocker is not configured to use the NVIDIA runtimeFix

What does the error look like?

  • nvidia-smi lists the GPU in the container, but a Vulkan program finds no NVIDIA device

Cause 1 of 4

The graphics capability is not enabled

1Check

The docs list graphics as the capability for OpenGL, EGL and Vulkan, and say an unset variable means utility and compute only.

docker inspect <container> --format '{{.Config.Env}}'

2Fix

Request graphics together with utility. The variable replaces the defaults, so list everything you need.

docker run --rm --gpus 'all,"capabilities=graphics,utility"' <image> <command>
# or in the Dockerfile:
ENV NVIDIA_DRIVER_CAPABILITIES=graphics,utility

3Verify

The Vulkan program lists the NVIDIA device.

docker run --rm --gpus 'all,"capabilities=graphics,utility"' <image> vulkaninfo

Confirmed by docs.nvidia.com

Did this fix it?

Cause 2 of 4

The container shows windows but only compute was requested

1Check

The display capability is for X11 or Wayland windows and implies graphics.

echo $NVIDIA_DRIVER_CAPABILITIES

2Fix

For a 3D app with a window, request compute, utility, graphics and display.

docker run --rm --runtime=nvidia \
  -e NVIDIA_VISIBLE_DEVICES=0 \
  -e NVIDIA_DRIVER_CAPABILITIES=compute,utility,graphics,display \
  <image> <command>

3Verify

The app opens its window and picks the NVIDIA GPU.

nvidia-smi

Confirmed by docs.nvidia.com

Did this fix it?

Cause 3 of 4

The wrong GPU is assigned to the container

1Check

With graphics enabled, EGL and Vulkan visibility is limited to the GPUs assigned to the container.

nvidia-smi -L

2Fix

Assign the GPU that drives your workload with NVIDIA_VISIBLE_DEVICES.

docker run --rm --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=0 -e NVIDIA_DRIVER_CAPABILITIES=graphics,utility <image> <command>

3Verify

The listed device matches the one you assigned.

nvidia-smi -L

Confirmed by docs.nvidia.com

Did this fix it?

Cause 4 of 4

Docker is not configured to use the NVIDIA runtime

1Check

The toolkit's install guide adds the runtime to /etc/docker/daemon.json with nvidia-ctk.

grep -n nvidia /etc/docker/daemon.json

2Fix

Configure the runtime and restart Docker.

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

3Verify

The GPU shows up in a test container.

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Confirmed by docs.nvidia.com

Did this fix it?

How do I stop it coming back?

  • Bake NVIDIA_DRIVER_CAPABILITIES into the image for graphics workloads.
  • Always list utility next to graphics; the variable replaces the defaults.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Servers

A dev container port does not open in the browser when Docker runs on a remote host

If your application only accepts calls from localhost, it will reject connections from published ports

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.