Key Concepts:

NVIDIA Container Toolkit

What is the NVIDIA Container Toolkit and how can it be used to run Linux containers with full GPU acceleration?

Key points:

  • The NVIDIA Container Toolkit (formerly known as NVIDIA Docker) allows Linux containers to access full GPU acceleration.
  • All graphics APIs are supported, including OpenGL, Vulkan, OpenCL, CUDA and NVENC/NVDEC.
  • This only works with NVIDIA GPUs for Linux containers running on Linux host systems or inside WSL2.



The NVIDIA Container Toolkit (formerly known as NVIDIA Docker) is a library and accompanying set of tools for exposing NVIDIA graphics devices to Linux containers. It provides full GPU acceleration for containers running under Docker, containerd, LXC, Podman and Kubernetes. If you are interested in learning about the underlying architecture of the NVIDIA Container Toolkit then be sure to check out the Architecture Overview page of the official documentation.

Containers running with GPU acceleration have access to all supported graphics APIs on NVIDIA GPUs, including OpenGL, Vulkan, OpenCL, CUDA and NVENC/NVDEC. For details of what these APIs are used for, see the GPU acceleration in containers overview page.

The NVIDIA Container Toolkit is designed specifically for Linux containers running directly on Linux host systems or within Linux distributions under version 2 of the Windows Subsystem for Linux (WSL2). The underlying code does not support Windows containers, nor can it be used when running Linux containers on macOS or Windows without WSL2 due to the fact that containers are run inside a Linux VM that does not have GPU access. However, Docker clients running under Windows and macOS can still be used to connect to a Docker daemon running under Linux with the NVIDIA Container Toolkit.

For details of alternative options for other GPU vendors and operating systems, see the GPU acceleration in containers overview page.

Installation under Linux

  1. As per the supported platforms list and prerequisites list from the NVIDIA Container Toolkit Installation Guide, you will need to ensure you have a supported Linux distribution and a supported NVIDIA GPU.

  2. Install a supported version of Docker Community Edition (CE) 18.09 or newer.

  3. Install the NVIDIA binary GPU driver, ensuring you use a version that meets the minimum requirements for the CUDA version you intend to use or at least version 418.81.07 if you don’t intend to use CUDA.

  4. Install the NVIDIA Container Toolkit by following the instructions for your specific Linux distribution.

  5. If you would like to test out a specific graphics API, pull the relevant NVIDIA base container images from Docker Hub:

  6. If you intend to use the Unreal Engine with a runtime container image then be sure to choose a base image that is pre-configured to support the NVIDIA Container Toolkit.

  7. If you intend to use the Unreal Engine with a development container image then you will need to choose an image source that supports the NVIDIA Container Toolkit. Depending on the graphics APIs that you are interested in using, it may be necessary to build a development image from source that extends the relevant NVIDIA base image.

Installation under Windows with WSL2

The authors of this documentation are still in the process of familiarising themselves with the use of the NVIDIA Container Toolkit under WSL2. This section will be updated when the relevant information has been gathered.

Container image compatibility

Container images built on a system that has the NVIDIA Container Toolkit installed will be identical to container images built on a system without the NVIDIA Container Toolkit. This is because GPU acceleration is not enabled during the build process. The resulting container images can be run with GPU acceleration using the NVIDIA Container Toolkit or without GPU acceleration using any OCI-compatible container runtime.

Older versions of NVIDIA Docker allowed the Docker daemon to use NVIDIA Docker as the default container runtime, which enabled GPU acceleration during image builds and meant that any container images built by that Docker daemon could be rendered non-portable. For this reason, it was strongly recommended that you did not reconfigure the default container runtime on hosts that were used to build containers. This option is not present in newer versions of the NVIDIA Container Toolkit.