ATOPGPUD(8)

📦
version 2.13.0 · 2 versions
, in arch rolling

🎀 ATOPGPUD(8) 🎀

okay so bestie, welcome to atopgpud — the GPU statistics daemon — straight out of the System Manager's Manual. she's on the Linux side of the fam and honestly she's kind of the backbone of the whole GPU-watching situation. let's get into it 💅

✨ SYNOPSIS ✨

atopgpud [-v]

that's it. that's the whole vibe check. one optional flag, no drama. 🦋

💖 DESCRIPTION 💖

so what does atopgpud actually do? she gathers statistical info from all the NVIDIA GPUs in the current system. with a sampling rate of one second, she keeps the stats of every single GPU — both globally (system level) and per process. and when atopgpud is active on the target system, atop (with the flag -k) connects to this daemon via a UNIX domain socket and pulls GPU statistics for each interval. the way they communicate… iconic. 🫶

okay but why a whole separate daemon, you ask? valid question, here's the tea ☕ — the NVIDIA driver only offers the GPU busy percentage of the last second. so imagine atop runs with a 10-minute interval and just fetched the GPU busy percentage directly from the NVIDIA driver — it would reflect the busy percentage of the last second instead of the average busy percentage during 600 seconds. not the move. 🙈 therefore atopgpud fetches the GPU busy percentage every second and accumulates it into a counter that atop can retrieve regularly. same approach applies to the other GPU statistics too. consistency queen 👑

good news: there is no need to run the atopgpud daemon with root privileges. she doesn't need the power, she's humble like that.

heads up bestie 🚨 — certain GPU statistics are only delivered for specific GPU types. for older or less sophisticated GPUs, the value -1 is returned for counters that are not maintained. in the output of atop, these counters show up as 'N/A'. not a bug, just the hardware being real about its limits 😭

and when no NVIDIA GPUs can be found in the target system, atopgpud immediately terminates with exit code 0. she simply leaves. no goodbye. 💀

log messages get written via the rsyslogd daemon with facility 'daemon'. and with the -v flag (verbose), atopgpud also logs debug messages. so if you want the whole story, you know what to do ✨

🌸 INSTALLATION 🌸

atopgpud is written in Python, so a Python 3 interpreter should be installed on the target system. the daemon depends on the Python module pynvml to interface with the Nvidia driver — you can install this module with the pip or pip3 command, and it's usually packaged under the name nvidia-ml-py. 🎀

also, the pynvml module is a Python wrapper around the libnvidia-ml shared library, and that needs to be installed as well. both of them, bestie. don't skip.

now — after installing the atop package, atopgpud is not automatically started, and the service will not be enabled by default. she waits for you to make the first move 💅 when you want to activate this service (permanently), enter the following commands as root:

systemctl enable atopgpu
systemctl start atopgpu

two lines. slay. done. ⭐

🦋 INTERFACE DESCRIPTION 🦋

client processes can connect to the atopgpud daemon using the abstract socket name 'atopgpud_nvidia'. once connected, such a client can send a request of two bytes, consisting of one byte request code followed by one byte integer being the API version number. 🧚

the request code in the first byte:

  • can be 'T' to obtain information about the GPU types installed in this system (usually only requested once)
  • can be 'S' to obtain all statistical counter values (requested for every interval)

now for the response 👑 — the response of the daemon starts with a 4-byte integer. the first byte is the API version number that determines the response format, while the subsequent three bytes indicate the length (big endian order) of the response string that follows.

in the response strings, the character '@' introduces system level information of one specific GPU, and the character '#' introduces process level information related to that GPU. 🌈

for further details about the meaning of the counters in a response string, please consult the source code. iykyk 💜

🔥 SEE ALSO 🔥

👑 AUTHOR 👑

Gerlof Langeveld (gerlof.langeveld@atoptool.nl) — the main character who wrote all this. respect. 🫡

and that's the whole page, bestie 💖 this edition dropped on Linux in September 2025, and honestly? ate. periodt. 🎀✨🌸

📦 where this page comes from