Inside nvitop: NVML bindings, a curses monitor, and nvisel
An interactive NVIDIA-GPU process viewer and beyond, the one-stop solution for GPU process management.
At a glance
- What is it?
- nvitop puts a curses interface in front of the NVML Python bindings, turning a one-shot GPU status table into a screen you can sort, filter and signal processes from. The same package also carries a CUDA device selection tool called nvisel, a separate exporter directory, and Device, Process and Host objects you can import.
- Who is it for?
- nvitop fits a single Linux or Windows host where somebody is already logged in and wants to see, sort and signal GPU processes from a terminal. It does not fit a fleet: the exporter lives in its own nvitop-exporter directory, and the console view shows one machine at a time.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 10 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- XuehaiPan/nvitop7,264 ★ · +100
| Repository | 2026-09-24 | 2026-11-21 |
|---|---|---|
| XuehaiPan/nvitop | 7.2k | 7.3k |
100 Stars in the last 58 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
NVML bindings instead of parsing nvidia-smi output
nvitop asks the driver for its numbers through the NVML Python bindings, the package nvidia-ml-py, rather than scraping the text nvidia-smi prints and reparsing it. The project names nvidia-htop as the contrast: that tool reads nvidia-smi output and shells out to `ps -p <pid>` for the host half of each process. nvitop drops both steps, taking device state from the binding and host process state from psutil, a cross-platform library.
Underneath sits NVML, a C interface for monitoring and managing device state, whose runtime version ships with the NVIDIA display driver or arrives with the CUDA Toolkit. That is the hard floor for everything else. No driver means no NVML means no device list and nothing to draw. The stated requirements are short: Python 3.8 or newer, NVML, nvidia-ml-py, psutil, and curses with libncursesw.
The payoff is that nvitop is ordinary Python. Every layer above the binding is an importable package, so one data path can serve a terminal screen, an exporter and a training callback.
TTLCache, threads and curses decide when the screen repaints
Three choices separate nvitop from the tools it names. Device status is queried sparsely and held in `TTLCache` from cachetools, a point the README sets against gpustat. Information is gathered asynchronously on multiple threads so user input gets a faster response, a point the README sets against nvtop. Output goes through the curses library rather than `print` with ANSI escape codes, where py3nvml prints.
The cache deserves a second look before you trust a number. A cached reading is one that has not been re-fetched, so on a saturated node the utilization figure on screen can lag the device. The feature list names cachetools and TTLCache without giving a cache interval.
Everything else is a curses screen. Monitor mode adds bar charts and history graphs, process sorting, process filtering, a tree view walking from a GPU process up to its parents, an environment variable screen, a help screen and mouse support. Sending a signal to a process takes one keystroke, which puts process termination in the same window as the graphs.
Four pinned dependencies, then python3 -m nvitop
`requirements.txt` is the entire runtime, four lines, with the two Windows packages marked by environment markers:
nvidia-ml-py >= 11.450.51, < 13.616.0a0
psutil >= 5.6.6
colorama >= 0.4.0; platform_system == 'Windows'
windows-curses >= 2.2.0; platform_system == 'Windows'Read the first line twice. The floor is 11.450.51, and the upper bound is exclusive: the pin stops below 13.616.0a0. The comments at the top of `setup.py` name the two ways past that, one pinning the binding yourself and one letting a CUDA major version arrive through an extra:
pip install nvidia-ml-py==xx.yyy.zz nvitop
pip install 'nvitop[cudaXX]'Both lines are templates, with the version and the CUDA major left blank on purpose. Once the package is in place, the invocation shows up in the Dockerfile entrypoint, and it is the module form:
ENTRYPOINT [ "/venv/bin/python3", "-m", "nvitop" ]Run that from inside the environment and the curses interface opens on the device and process status view.
install-nvidia-driver.sh wants tty3 before it touches the driver
A monitoring package that also carries a driver installer is unusual enough to name. `install-nvidia-driver.sh` sits at the top of the repository and installs or upgrades NVIDIA drivers on Ubuntu Linux from ppa:graphics-drivers. `pip install` never runs it. A user with no driver has to leave Python entirely, clone the repository and run a root shell script:
git clone --depth=1 https://github.com/XuehaiPan/nvitop.git && cd nvitopOn a desktop running a GUI, one step comes first. The README marks that console switch as required for desktop users on tty2 and optional for SSH users, so the order matters:
sudo chvt 3
bash install-nvidia-driver.sh --package=nvidia-driver-595
bash install-nvidia-driver.sh --latest
bash install-nvidia-driver.sh --latest --openThree shapes of one call: a named package version, whatever that PPA calls latest, and latest with the open kernel module. `bash install-nvidia-driver.sh --help` covers the remaining options. If the box already has a working driver, none of this applies and you can go straight to the virtual environment.
The container build refuses anything but Ubuntu
The Dockerfile at the repository root opens with a distribution check that fails loudly instead of adapting:
RUN . /etc/os-release && [ "${NAME}" = "Ubuntu" ] ||
(echo "This Dockerfile is only supported on Ubuntu" >&2 && exit 1)Behind the guard the image is deliberately plain: `ubuntu:latest`, then `python3-dev`, `python3-venv` and `locales`, a `C.UTF-8` locale, a virtual environment at `/venv`, and the package installed into it. The header comment gives the build command:
docker build --tag nvitop:latest .Two consequences for anyone reaching for containers. The guard reads /etc/os-release inside the image, and the base is `ubuntu:latest`, so it only stops the build if the base image is swapped for a non-Ubuntu one. And nothing in the file opens a port or declares an EXPOSE, because the entrypoint is a terminal program. What you get is a curses interface that needs a TTY attached: an interactive monitor you exec into, not a service something else scrapes.
On Windows the mouse depends on the terminal emulator
curses is a built-in module of Python on Unix-like systems. On Windows it arrives through a third-party package, windows-curses, with colorama handling colour on the same platform.
The feature list includes mouse support. The README's own screenshot caption records the environment it was captured in, PowerShell as the shell, Windows Terminal as the terminal, Windows 10, locale en-US, so the combination is confirmed there and unconfirmed elsewhere.
The keyboard path is the portable one. Monitor mode is described as responsive to user input from keyboard and/or mouse, and sorting, filtering, the tree view and signal sending are all reachable without the pointer.
The examples directory is the real API documentation
Beyond the screen, the package is meant to be imported, and `examples/` holds ten directories. They split three ways: monitors (`monitor-minimal`, `monitor-colored`, `monitor-rich`, `monitor-web`), collectors (`collector-csv`, `collector-background`, `collector-tensorboard`), and integrations (`ml-framework-callbacks`, `select-devices-api`, `take-snapshots`).
The usage sections name what sits behind them, with headings for a Quick Start, a Status Snapshot, a Resource Metric Collector, and low-level APIs for Device, Process and Host, where Host is inherited from psutil rather than reimplemented. The collectors matter most if you want history rather than a screen.
The full API reference is hosted at nvitop.readthedocs.io, and the tree carries both `docs/` and `.readthedocs.yaml`. The `nvitop-exporter/` directory at the top level is separate again, and the README links a Grafana dashboard built on top of it.
Apache-2.0 in the index, Apache-2.0 AND GPL-3.0-only in pyproject.toml
The repository index reports the licence as Apache-2.0. `pyproject.toml` says something wider: `license = { text = "Apache-2.0 AND GPL-3.0-only" }`, with classifiers for both the Apache Software License and GNU General Public License v3, and a `COPYING` file at the top level. Two different statements about one tree, so anyone vendoring the code has to open `COPYING` and work out which obligations attach to their use.
Upgrades are frequent and the edges are sharp. The three most recent releases are v1.7.0 on 2026-05-16, v1.7.1 on 2026-07-10 and v1.7.2 on 2026-10-26. The classifiers cover Python 3.8 through 3.15 and `requires-python` is `>= 3.8`, so a current interpreter is not a constraint. The edge is the binding pin: when NVIDIA publishes a new nvidia-ml-py, that ceiling has to move before the package installs against the new driver. The last push to the default branch was on 2026-11-02.
Editorial conclusion
nvitop fits a single Linux or Windows host where somebody is already logged in and wants to see, sort and signal GPU processes from a terminal. It does not fit a fleet: the exporter lives in its own nvitop-exporter directory, and the console view shows one machine at a time. It cannot help a host with no NVIDIA driver either, since the NVML library it binds to ships with the driver or the CUDA Toolkit. Before installing, check the nvidia-ml-py build already on the box against the floor of 11.450.51 and the ceiling of 13.616.0a0, because pip will not install a binding at or above that ceiling.
Frequently asked questions
What is the nvitop command?
nvitop is an interactive NVIDIA device and process monitoring tool written in pure Python and launched as `python3 -m nvitop`. It draws a curses interface that continuously updates the status of devices and processes, and it installs with pip.
What are the differences between nvitop and nvtop?
nvitop is written in pure Python and installs with pip, while nvtop does not. nvitop also gathers information asynchronously using multi-threading so it can respond to user input faster, and it exposes importable APIs so other applications can reuse the same data.
How do I use nvitop?
Run it with `python3 -m nvitop` and the curses interface opens on the device and process status view. In monitor mode you get bar charts and history graphs, process sorting and filtering, a tree view of GPU processes and their parents, an environment variable screen and a help screen.
How do I install nvitop?
requirements.txt pins the runtime to nvidia-ml-py between 11.450.51 and 13.616.0a0, psutil 5.6.6 or newer, plus colorama and windows-curses on Windows, and the comments in setup.py show how to pin nvidia-ml-py yourself or use the cudaXX extra.
Official sources
Where developers are discussing it
Posts on Hacker News, dev.to and Lobsters that link to this repository, found by our scan of those communities. 0 in the last 30 days; newest first.
- Nvitop: A better top for Nvidia GPUsHacker News · Sep 23, 2026 · 1 points · 1 comments
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/xuehaipan-nvitop)Star history chart for your README
[](https://hysenlabs.com/projects/xuehaipan-nvitop)Was this useful?