NVTOP on Linux: the kernel floor that hides your GPU processes

Per-process rows come from driver fdinfo, not from NVTOP

The interesting half of NVTOP is the list of processes holding a device, and that list is not produced by NVTOP. It is produced by each kernel driver exposing an fdinfo interface, which NVTOP reads through the DRM and sysfs paths. That is why the vendor list in the documentation is written as driver names rather than as marketing names: AMD through amdgpu and the legacy radeon driver, Intel through i915 or xe, Qualcomm Adreno through msm, Broadcom VideoCore through v3d, Rockchip, MetaX through MXSML, Enflame through EFML and Tenstorrent through tt-kmd.

Other vendors arrive through their own vendor libraries instead. NVIDIA goes through the NVML library, Huawei Ascend through the DCMI API, Iluvatar CoreX through the ixML library, and Apple through Metal. Multiple GPUs are handled in one interface, printed the way htop prints processes.

The consequence for a reader is a division of labour worth remembering. The per-process rows on AMD, Intel and Adreno depend on what the kernel driver publishes. A field can be missing for a reason that has nothing to do with NVTOP's version.

Kernel 5.14, 5.19 and 6.0 are the floors for AMD, Intel and Adreno

Three of the vendors have a dated threshold, and the documentation gives the kernel source file where the interface appeared. AMD introduced the fdinfo interface in kernel 5.14, in amdgpu_fdinfo.c. Intel introduced it in kernel 5.19, in i915_drm_client.c. The msm driver for Adreno introduced it in kernel 6.0, in msm_drv.c.

Below those versions you get the device row and no process rows. The AMD section adds a second condition: the legacy radeon driver works but provides limited metrics compared with amdgpu, so a card still driven by radeon will look thinner than the same card on amdgpu.

There is also a moving target on the hardware side. The documentation notes that support for recent GPUs is regularly mainlined into the Linux kernel and asks you to use a recent-enough kernel for your GPU. On an older enterprise kernel, a newly bought card can be invisible for the same reason, and no NVTOP build fixes that.

Intel total memory and clock need CAP_PERFMON on the binary

Intel is the one vendor where the documentation tells you to change permissions. Total memory usage and an accurate GPU frequency require CAP_PERFMON or CAP_SYS_ADMIN capabilities, and the documented way to grant just the one you need is a file capability on the binary:

sudo setcap cap_perfmon=ep $(which nvtop)

Running nvtop as root is given as the alternative. A file capability travels with the binary, so every user who executes that path holds it. Running as root hands the whole monitor more privilege than the two counters require.

Treat setcap as a change to your machine rather than a debugging step. Without the capability, the README says Intel total memory usage and an accurate GPU frequency cannot be accessed.

nvtop -i and nvtop -X need libnvidia-api.so.1 and degrade without it

The NVIDIA backend splits into two libraries, and only the first is guaranteed. NVML covers the ordinary queries, with the documented caveat that it does not support some queries for GPUs older than the Kepler microarchitecture, so anything from GeForce 600 and GeForce 800M onwards is the workable range and older cards are a matter of trial against the NVML documentation.

The second library is NvAPI, installed by recent drivers alongside NVML as libnvidia-api.so.1. It is what feeds the extra GPU info bar opened with nvtop -i, which shows dynamic parameters NVML does not report such as the XBAR, SYS and NVD clocks, and the bar opened with nvtop -X, which adds static specifications such as shader cores, L2 cache and execution engines plus the secondary HUB, HOST, DISP, MSD and UTILS clocks.

What makes this worth documenting is the failure behaviour. Without that library the rest of the interface is unaffected and the bar takes no room on a GPU that reports nothing, so a missing bar is a missing optional dependency rather than a broken driver.

The Dockerfile builds with cmake and runs with --gpus all --pid host

The repository ships a Dockerfile, and its header comments give the two commands you need. The build is plain CMake and make in a builder stage:

docker build . -t nvtop

The base image is a build argument defaulting to nvidia/opengl:1.2-glvnd-runtime-ubuntu20.04, and the comments name the alternatives that can be substituted with --build-arg IMAGE=nvcr.io/nvidia/cudagl:11.4.2-base-ubuntu20.04 or nvidia/driver:418.87.01-ubuntu18.04. The builder stage installs build-essential, wget, libncurses5-dev, libncursesw5-dev, libssl-dev, pkg-config, libdrm-dev, libgtest-dev, libudev-dev and python3-venv, then installs cmake through pip inside a virtualenv because the base image ships an old one. The compile step is:

cmake ..
make -j
make install

The run command is the interesting part:

docker run --rm -it --gpus all --pid host nvtop

--gpus all passes the devices and --pid host is what lets the container see host processes at all. The final stage copies only the binary and the manpage, and sets the entrypoint to /usr/local/bin/nvtop.

Once it is running, the interface is configured from the keyboard. Press F2 for the setup window, where the Chart section chooses which metrics are plotted: GPU and memory utilization, temperature, power, clocks, and the PCIe RX / TX load expressed as a percentage of maximum link bandwidth. Press F12 to save those preferences, and they are loaded the next time you run nvtop. The rest of the command line reference lives in the manpage:

man nvtop
nvtop -h
nvtop --help

Ascend, Apple and Iluvatar backends are opt-in at compile time

Ascend is enabled with a build flag, Apple support depends on the build platform, and Iluvatar CoreX depends on a library found at run time.

Ascend is the explicit one. It is enabled with -DASCEND_SUPPORT=ON, and -DASCEND_ROOT=/path/to/Ascend is needed when CANN sits outside the standard locations. It talks the DCMI API, uses the logical-device API when available and falls back to the legacy card and device API, reports read-only telemetry where the installed driver supports it, and leaves unavailable values unset. The documentation says it is tested on 910B hardware, with one section naming 910B3 specifically, so treat other Ascend parts as unverified.

Apple is opt-in by platform rather than by flag. Apple support is built only when building for Apple, and in an Apple build it is the only vendor supported. It is described as initial support with limited M1 and M2 coverage, still being worked on, with bugs and limitations expected.

Iluvatar CoreX loads libixml.so dynamically from /usr/local/corex/lib, /usr/local/corex/lib64, or the default loader search path. Its ixML runtime presents an NVML-compatible surface for device, power, PCIe, clock, temperature, memory and process queries, so an install outside those two directories only works if the loader can find the library.

Rockchip reports NPU frequency only, VideoCore reports per-process

The single-board-computer backends are not uniform, and the difference matters if you are sizing a cluster of SBCs.

VideoCore on Broadcom is tested on a Raspberry Pi 4B and reports GPU frequency, temperature, utilization, per-process utilization, GPU memory usage and H264 decoding utilization. Outside Raspberry Pi OS there are two conditions: you need the linux-rpi 6.12.y kernel or above, and the /dev/vcio device must be present.

Rockchip is tested on an orangepi 5 plus and reports only NPU frequency, temperature and utilization. There is no per-process figure in that list, which is the practical difference between the two: on Rockchip you can see that the accelerator is busy and not which process made it busy.

MetaX is tested on an MXC500 through the MXSML library, and Enflame and Tenstorrent are listed with their Linux EFML and tt-kmd drivers.

No native Windows build, and the licence field resolves to NOASSERTION

Every documented installation route is a Linux one: Ubuntu and Debian from Impish 21.10 and Debian buster onward, Fedora, Red Hat and CentOS, OpenSUSE, Arch, Gentoo, an AppImage, a Snap package, Conda-forge, Docker, and WSL2. There is no native Windows package in that list, so a search for an NVTOP Windows build lands on a curses tool that expects DRM, sysfs and Linux vendor libraries. WSL2 is the route the documentation offers for Windows users, and inside it you are back to the kernel floor problem described earlier.

The release history tells you where the tip of the tree sits. Version 3.3.0 was tagged on 2026-01-16, 3.3.1 on 2026-01-18 as a bugfix release, and 3.3.2 on 2026-02-08, while the last push to the master branch was on 2026-10-04 and the repository is not archived. So the default branch is roughly eight months ahead of the newest tag, which means a distribution package can be well behind the fixes you read about in the repository.

Licence is the last loose end. The repository root holds both a COPYING file and a LICENSE file, and the project is C with a master default branch, yet the licence field resolves to NOASSERTION. That is a detection failure rather than a licence statement. Open those two files before you redistribute a binary or build it into an image, because no badge in the documentation will answer the question for you.

Editorial conclusion

NVTOP is the right tool on a Linux box where you need to see which process is eating a GPU, provided you read the kernel floor for your driver before you trust an empty process list, and provided you are willing to grant CAP_PERFMON on Intel. It is not a Windows tool: the documented installation routes are Linux distributions, AppImage, Snap, Conda-forge, Docker and WSL2, and no native Windows build appears. Before shipping anything built on it, read the COPYING and LICENSE files in the repository root yourself, since the licence field resolves to NOASSERTION. If you need static hardware specs, remember that the README documents them for the NVIDIA path, through nvtop -X.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. Syllo/nvtop on GitHub