jetson-stats: jtop monitoring and control for NVIDIA Jetson boards

What jetson-stats solves on a Jetson board

NVIDIA Jetson boards do not expose their state through the same interfaces as a desktop GPU or a normal ARM server. The README describes jetson-stats as a package for monitoring and control of the Thor, Orin, Xavier, Nano and TX series, and lists what it decodes: hardware, architecture, L4T and NVIDIA Jetpack versions, plus CPU, GPU, memory, engines and fan. That list is the product. On a Jetson you often need to know which Jetpack release the image carries before you can reason about anything else, and that information is not in a standard place. The package is aimed at developers and embedded engineers working on the board itself, not at data centre operators managing racks of discrete GPUs. It also claims it does not need super user, which matters on a shared dev kit where you do not want to hand out root just to watch temperatures. The control side covers NVP model, fan speed and jetson_clocks, so the same tool both reads and changes the power and cooling configuration.

How jtop reads the board and where the data comes from

The architecture visible in the repository splits into a service and clients. The top level contains a jtop package, a services directory and a scripts directory, and the Docker instructions tell you to pass /run/jtop.sock into a container. That socket is the boundary. The host runs the service, clients connect over the socket, and a container gets access by bind mounting it. This is why the README says you must install jetson-stats on the host and also inside the container: the client library is needed on both sides of the mount. On the data side, requirements.txt lists smbus2, distro and nvidia-ml-py. smbus2 points at I2C access, which is how board sensors are typically reached, distro is used to identify the Linux distribution, and nvidia-ml-py is the NVIDIA Management Library binding. The library interface reflects the same polling model: you open a jtop() context manager and loop while jetson.ok(), reading jetson.stats on each pass. The documentation describes ok() as providing the proper update frequency, so the loop is paced by the library rather than by your own sleep call.

Installing jetson-stats and running jtop the first time

The README starts with the system packages, then offers several pip routes. The first two commands update apt and install pip and setuptools, which the package expects to be present.

sudo apt update
sudo apt install python3-pip python3-setuptools -y

The straightforward install uses pip with superuser rights. The README shows the -U flag to upgrade an existing copy in place.

sudo pip3 install -U jetson-stats

On Ubuntu 24.04 the README notes that pip refuses to install into the system environment without an override, and gives this variant.

sudo pip3 install --break-system-packages -U jetson-stats

There is also a script route for running jtop with or without sudo. The README says this method works on all Jetson Developer Kits and points AGX Thor Dev Kit users at the same script. Note that it pipes a remote script into bash, so read it before running it on a board you care about.

sudo -v
curl -LsSf https://raw.githubusercontent.com/rbonghi/jetson_stats/master/scripts/install_jtop_torun_without_sudo.sh | bash

After install, the README says starting jtop is just the command name. A terminal interface appears and the rest is documented on the jtop page of the project site.

jtop

For scripted use, the README gives this example, which opens the connection, loops at the library's update frequency and prints the stats dictionary.

from jtop import jtop

with jtop() as jetson:
    # jetson.ok() will provide the proper update frequency
    while jetson.ok():
        # Read tegra stats
        print(jetson.stats)

The examples directory in the repository is the place to look next. It contains separate files for callbacks, control, cpu, engines, fan, hardware, memory, processes, properties, a Flask server, a plain server and a quick read, so you can copy the shape of the call you need instead of guessing at the API.

The Docker path and its two-sided install requirement

Running jtop in a container is documented as a three step procedure: install jetson-stats on the host, install it in the container as well, and pass /run/jtop.sock through. The README gives a one-line example using the published image.

docker run --rm -it -v /run/jtop.sock:/run/jtop.sock rbonghi/jetson_stats:latest

This is a design constraint rather than a convenience. Because the client talks to a Unix socket on the host, the container cannot be self-contained; it depends on the host having the service running and on the socket path being identical inside and outside. The repository Dockerfile builds from python:3.13.6-slim-bullseye, copies the tree into /jetson_stats, upgrades pip, installs the package with pip3 install -v . and sets the command to jtop. That image is a client. If you build your own container on top of it, you inherit the same socket dependency, and any orchestration that does not bind mount /run/jtop.sock will leave you with a jtop that has nothing to read.

Where jetson-stats is the wrong tool

The package is specific to NVIDIA Jetson hardware. If your workload runs on discrete GPUs in a server, on x86 machines with consumer cards, or on non-NVIDIA ARM boards, the hardware decoding and the sensor paths have nothing to talk to. The README claims it works with all NVIDIA Jetpack versions, but the search data around this project includes people hitting detection failures, which is the predictable outcome when a board or an L4T release is newer than the decoder tables in the installed version. Treat the Jetpack claim as a support target, not a guarantee for the image you happen to be running. The second limitation is scope: jetson-stats is a monitor and a control surface, not a metrics pipeline. There is no HTTP endpoint in the README, no Prometheus exposition, and no retention. If you need long-term graphs or alerting across a fleet, you will be writing the exporter yourself on top of the library, and the search data around a node exporter for this project suggests people are looking for exactly that and not finding it in the box. The third is the licence, covered below.

Alternatives and how their approach differs

tegrastats ships with the L4T image and is the baseline. It prints a line of counters to stdout at an interval you choose, and it has no client library, no socket, no interactive interface and no control functions. If you only need a raw stream to parse yourself, tegrastats is already on the board and adds nothing to your dependency list. jetson-stats differs by decoding those counters into named fields, presenting them in a terminal UI, and adding control of NVP model, fan speed and jetson_clocks. The trade is a Python package, a background service and a socket on the host. The other common alternative is to query the NVIDIA Management Library directly, since nvidia-ml-py is already a dependency here. That gives you the raw NVML surface without the Jetson-specific decoding or the service layer, and it is the better choice if you only need GPU utilisation and memory from a process you already control. You lose the board-level information: architecture, L4T and Jetpack identification, engine states and fan control are jetson-stats territory, not plain NVML.

Licence, maintenance and upgrade cost

The package is AGPL-3.0, stated in pyproject.toml, in the LICENSE file and in the source headers, and the classifier line says GNU Affero General Public License v3 or later. This is not a permissive licence. If you embed jetson-stats in a product you distribute, or expose it as part of a network service, the copyleft terms of the AGPL are the thing to read before you build on it. That is a question for your own legal review, not something this article can settle. On maintenance, the last push to the default branch was on 2026-08-09, and the most recent release listed is 7.2.1 on the same date, with 7.2.0 on 2026-07-14 and 7.1.5 on 2026-03-24. The repository is not archived. The upgrade path is the same command as the install, with -U, plus a separate script the README provides for the jtop-without-sudo setup. Since the host and any container must run compatible versions to talk over /run/jtop.sock, an upgrade is a two-sided operation on containerised deployments.

Reading stats in a loop without blocking your application

The library example is deliberately small, and the pattern it encodes is worth following. You do not call a getter and wait; you enter the context manager and iterate while ok() returns true. The documentation describes ok() as supplying the update frequency, so the loop body should be cheap. Printing the whole jetson.stats dictionary on every pass, as the README example does, is fine for a quick read and wrong for anything long-running. The examples directory separates concerns for exactly this reason: jtop_callback.py for callback-driven updates, jtop_logger.py for logging, jtop_flask_server.py and jtop_server.py for serving the data outward, and individual files for cpu, memory, engines, fan and processes. Pick the file that matches your intent rather than starting from the two-line snippet. One more practical point: because the client reaches the board through the jtop service, a script that works when run directly can fail under a different user or inside a container purely because the socket is not reachable. Check that /run/jtop.sock exists before debugging your own code.

Editorial conclusion

Adopt jetson-stats if you run NVIDIA Jetson hardware and want a terminal view of CPU, GPU, memory, engines and fan state, or if you want to pull the same numbers into a Python script. Skip it if your fleet is not Jetson, if you need an HTTP metrics endpoint out of the box, or if AGPL-3.0 does not fit how you distribute your product. Before you commit, confirm that your L4T and Jetpack combination is decoded correctly on one board, check that /run/jtop.sock appears after install, and read the licence text against your own distribution model.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes