libnvidia-container configures GPUs inside a container without knowing the runtime

The library prepares the container, the runtime starts it

The repository provides a library and a simple CLI utility to automatically configure GNU/Linux containers leveraging NVIDIA hardware.

The implementation relies on kernel primitives and is designed to be agnostic of the container runtime. That sentence is the whole design.

A GPU in a container is not a file mount. The device node, the kernel modules that make the driver work, the shared library and firmware files the driver needs, the device cgroup permissions, and the ld.so configuration that lets a process inside the container find the driver all have to be in place before the container's first process starts. Doing that inside the runtime's own configuration means every runtime needs its own implementation.

So the work is factored out. libnvidia-container does the preparation, using the kernel interfaces directly, and a runtime integration calls it. The README points at the nvidia-container-runtime project for the container runtime example, which is the integration that most people meet first.

The primary language is C, which is the right choice for a library that has to sit under a container runtime and talk to the kernel, and the repository is under the Apache-2.0 licence in its metadata. The README says the project is released under the BSD 3-clause licence, and the tree carries `COPYING` and `COPYING.LESSER` alongside `LICENSE`, so the files in the root are the reference for the terms.

There is one further licensing wrinkle, and the README states it plainly. The project can be dynamically linked with libelf from the elfutils package, in which case additional terms apply, and the NOTICE file is where to read them.

The releases are v1.20.1 from 2026-09-28, v1.20.0 and v1.19.1 both from 2026-08-13, and the last push was on 2026-09-28.

Installing from packages, images or a local build

There are three routes, and the one most people take is the package.

The package repository is published for your Linux distribution, and the installation is two package names.

libnvidia-container1
libnvidia-container-tools

The split matters. The first is the library itself, and the second is the tooling, which is where `nvidia-container-cli` and the configuration utilities live. A system that only needs the library for another integration does not need the tools, and a build pipeline that produces a container image needs both.

From source, the Docker route generates images for a specific distribution.

# Generate docker images for a supported <os><version>
make {ubuntu18.04, ubuntu16.04, debian10, debian9, centos7, amazonlinux2, opensuse-leap15.1}

# Or generate docker images for all supported distributions in the dist/ directory
make docker

The resulting images have the name `nvidia/libnvidia-container/<os>:<version>`, and the `make docker` target produces the full set into the `dist/` directory.

Without Docker, the build is a single make target.

make install

# Alternatively in order to customize the installation paths
DESTDIR=/path/to/root make install prefix=/usr

The `DESTDIR` and `prefix` variables are the standard packaging escape hatches, and the Makefile in the repository sets the defaults, with `prefix` at `/usr/local` and the binaries, libraries, documentation and pkg-config files derived from it. The `DIST_DIR`, `PKG_DIR` and `SRCS_DIR` variables point at `dist/`, `pkg/` and `src/` in the tree.

The list of supported distributions in the docker target is itself a fact about the project. It names Ubuntu 16.04 and 18.04, Debian 9 and 10, CentOS 7, Amazon Linux 2 and openSUSE Leap 15.1, which are the releases the build was written against when that list was written.

The command line example is the real documentation

The README's command line example is not a quick start, it is a specification of what the library does, and it is worth reading closely.

The sequence creates a namespace, builds a root filesystem, mounts the standard filesystems, and then calls the CLI to configure the container for one GPU.

cd $(mktemp -d) && mkdir rootfs
sudo unshare --mount --pid --fork

curl http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.6-base-amd64.tar.gz | tar -C rootfs -xz
useradd -R $(realpath rootfs) -U -u 1000 -s /bin/bash nvidia
mount --bind rootfs rootfs
mount --make-private rootfs
cd rootfs

mount -t proc none proc
mount -t sysfs none sys
mount -t tmpfs none tmp
mount -t tmpfs none run

And then the part that is the point of the whole repository.

nvidia-container-cli --load-kmods configure --ldconfig=@/sbin/ldconfig.real --no-cgroups --utility --device 0 $(pwd)

Reading the flags tells you what the library actually does. `--load-kmods` loads the kernel modules the driver needs. `--ldconfig=@/sbin/ldconfig.real` points at the real dynamic linker configuration rather than the container's, so the driver's libraries are found. `--no-cgroups` and `--utility` are device permission handling, and `--device 0` isolates the first GPU, which is the sentence in the README about isolating the first GPU device along with basic utilities.

The last steps complete the jail, with `pivot_root . mnt`, `umount -l mnt` and an `exec chroot --userspec 1000:1000 . env -i bash`, and then `nvidia-smi -L` from inside the container proves the GPU is there.

The fact that this works with `unshare` and `chroot`, with no container runtime in sight, is the clearest demonstration of the runtime agnostic claim.

Build flags decide what gets compiled in

The Makefile in the repository root is short, and the top of it is the interesting part, because the optional features are switches.

WITH_NVCGO   ?= yes
WITH_LIBELF  ?= no
WITH_TIRPC   ?= no
WITH_SECCOMP ?= yes

The question mark means each of these can be overridden on the command line or in the environment, so a distribution packager can turn a feature off for their build. The defaults are the interesting part, because they describe the shape of the project as shipped.

`WITH_NVCGO` defaults to yes. `WITH_LIBELF` defaults to no, which is the switch that corresponds to the licensing note in the README, since linking libelf from elfutils brings additional terms. `WITH_TIRPC` defaults to no, which is about the TI-RPC transport for the remote client. And `WITH_SECCOMP` defaults to yes, so the library can generate and apply a seccomp filter.

That last one is worth pausing on. A tool that runs before a container's first process and manipulates what that process is allowed to do needs to constrain itself, and building seccomp support in by default rather than as an option is a deliberate choice about the default posture.

The Makefile also includes `mk/common.mk` and `mk/docker.mk` from the `mk/` directory, and it defines a `DOC_FILES` list of `NOTICE`, `LICENSE`, `COPYING`, `COPYING.LESSER` and `THIRD_PARTY_NOTICES.md`, with targets including `install`, `uninstall`, `dist`, `third-party-notices` and `check-third-party-notices`. The last two are how the project keeps the licence documentation of its dependencies honest, and the `THIRD_PARTY_NOTICES.md` file in the repository root is the output of that process.

Where the library is the wrong answer

The limitation of this project is that it is infrastructure underneath a runtime, and it is very easy to reach for it directly when you should not.

The first case is the ordinary one. If the goal is to run a container with a GPU on a machine with an NVIDIA driver, the packaged path is the one to take, and the vendor runtime is a better answer than assembling namespaces by hand. Reaching for libnvidia-container directly means taking on the job that the runtime integration was written to do, and the integration is the part that keeps working when the driver layout changes.

The second case is a non-NVIDIA or non-Linux target. The library is explicitly about GNU/Linux containers and NVIDIA hardware. It relies on kernel primitives and NVIDIA's device model, so there is no version of this that helps with an AMD GPU, with Apple silicon, or with a container runtime that does not run on Linux.

The third is the licensing surface. The project is BSD 3-clause in the README, which is permissive, but the libelf linking brings additional terms, and a distribution that ships this has to carry `NOTICE`, `COPYING`, `COPYING.LESSER` and `THIRD_PARTY_NOTICES.md` and keep them accurate. For a vendor building a device support package, that is a maintenance obligation rather than a one-off.

The alternative approach, and the difference in approach is real, is to let the container runtime own the problem. The nvidia-container-runtime project is that approach, and it exists because the same preparation has to happen somewhere. The trade is between a library that any runtime can call and a runtime that owns the preparation itself. Teams with one runtime and no appetite for gluing components together should use the runtime, and teams with several runtimes, or with a runtime they do not control, should look at what this library does.

Editorial conclusion

libnvidia-container suits a platform engineer who wants the GPU plumbing separated from the container runtime, or anyone who needs to run an NVIDIA container somewhere the vendor runtime is not the right answer. It is the wrong project to reach for when you only want to run a container with a GPU, since the packaged runtime path is simpler for that. Check first which package variant your distribution provides, since the library and the tools are separate packages, and note the licensing detail in the repository root before you vendor the code.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. NVIDIA/libnvidia-container on GitHub
4. README
5. Releases