Vulkan finds no NVIDIA GPU inside a Docker container
nvidia-smi lists the GPU in the container, but a Vulkan program finds no NVIDIA deviceShort 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.
Fix it fast
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'2Match what you see, then jump to its fix
- 1
nvidia-smi works, Vulkan or OpenGL fails; the variable is emptyThe graphics capability is not enabledFix - 2
An X11 or Wayland app needs a window as well as VulkanThe container shows windows but only compute was requestedFix - 3
Several GPUs on the host; Vulkan shows none or the wrong oneThe wrong GPU is assigned to the containerFix - 4
--runtime=nvidia is rejected, or no GPU appears at allDocker is not configured to use the NVIDIA runtimeFix
- 1
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,utility3Verify
The Vulkan program lists the NVIDIA device.
docker run --rm --gpus 'all,"capabilities=graphics,utility"' <image> vulkaninfoConfirmed by docs.nvidia.com
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_CAPABILITIES2Fix
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-smiConfirmed by docs.nvidia.com
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 -L2Fix
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 -LConfirmed by docs.nvidia.com
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.json2Fix
Configure the runtime and restart Docker.
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker3Verify
The GPU shows up in a test container.
docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smiConfirmed by docs.nvidia.com
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
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
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