XuehaiPan/nvitop

nvitop – Interactive NVIDIA‑GPU Process Viewer

What it is

• A pure‑Python, cross‑platform command‑line tool that shows detailed, colour‑rich information about NVIDIA GPUs and the processes using them. It can run once (like nvidia‑smi) or stay in a live “monitor” mode with interactive controls.

Why it matters for AI/ML

• Deep‑learning workloads run on NVIDIA GPUs. Knowing which jobs are using which GPU, their memory/utilisation, and being able to kill or signal runaway processes is essential for researchers and engineers managing shared clusters or single‑machine workstations.

Key features

• Rich output – more fields than nvidia‑smi (e.g., process tree, environment variables) with colourised box‑drawing.
• Monitor mode – live updating view with bar charts, history graphs, process sorting/filtering, and mouse/keyboard interaction.
• Process control – send SIGINT/TERM/KILL to selected processes directly from the UI (admin can sudo nvitop).
• CUDA‑visible‑devices selector – the bundled nvisel tool helps set CUDA_VISIBLE_DEVICES for experiments.
• Cross‑platform – works on Linux and Windows (uses windows‑curses on the latter).
• Fast & efficient – talks to the NVIDIA Management Library (NVML) via the nvidia‑ml‑py bindings, caches queries with cachetools, and gathers data in background threads.
• Integrable – provides low‑level Python APIs (Device, Process, Host) for building custom monitoring scripts or dashboards.
• Exporter & Grafana support – a separate nvitop‑exporter can push metrics to Prometheus/Grafana.

Installation

# Recommended: run in an isolated env via uvx or pipx
uvx nvitop          # or
pipx run nvitop

# Or install from PyPI / conda‑forge
pip install -U nvitop
conda install -c conda-forge nvitop

You can also install directly from the GitHub repo with pip install git+https://github.com/XuehaiPan/nvitop.git.

Basic usage

• One‑shot query (like nvidia‑smi): nvitop -1
• Show only GPUs 0 and 1: nvitop -1 -o 0 1
• Live monitor (default): nvitop
• Switch monitor layout: -m auto|full|compact (or press a, f, c inside the UI)
• Filter to processes with compute context: -c
• Use only ASCII characters (for plain terminals): -U
• Read‑only mode (no kill/terminate shortcuts): --readonly

Interactive controls (monitor mode)

Key	Action
Ctrl‑C / T / K	Interrupt / terminate / kill the selected process
t	Open tree‑view screen (recommended for sending signals)
Enter	Open per‑process metrics screen with live graphs
h	Show help screen
q	Quit
Arrow keys / mouse	Navigate rows

CUDA‑visible‑devices selector

• Run the companion CLI nvisel to interactively pick which GPUs should be visible to a new process, simplifying experiment setup.

Beyond a monitor

• The package ships a resource‑metric collector (nvitop‑exporter) that can expose GPU stats to Prometheus, enabling Grafana dashboards (see the screenshot in the README).
• Low‑level Python APIs let developers embed GPU status checks into their own tools or notebooks.

Requirements

• Python 3.8+
• NVIDIA driver with the NVML library (bundled with the driver or CUDA toolkit)
• nvidia‑ml‑py, psutil, and on Unix curses (Windows needs the windows‑curses package).

Documentation & support

• Full API docs: https://nvitop.readthedocs.io
• PyPI page, conda‑forge package, and GitHub issues for bug reports.

---

nvitop is a practical utility for anyone running AI/ML workloads on NVIDIA GPUs, giving a richer, interactive view of GPU health and process usage than the standard nvidia‑smi tool.