gpustat is a Python command-line utility that queries and monitors NVIDIA GPU status, built for developers, researchers, and cluster operators who want a more readable view of GPU usage than raw nvidia-smi output.

What it is

gpustat is an MIT-licensed Python tool distributed on PyPI that reports the state of NVIDIA graphics devices from the terminal. It queries the hardware through NVML using NVIDIA's official nvidia-ml-py binding, then prints a compact, colorized per-GPU summary — utilization, memory, temperature, power, and the processes holding resources — in a single command. It ships both as a command-line program and as an importable library, so the same query surface can be embedded in other Python code.

The concrete problem it solves is the friction of day-to-day GPU inspection. nvidia-smi is authoritative but verbose, and getting per-process detail out of it means reading wide tables or wiring up format flags. gpustat presents the same underlying device data as a tighter, consistently formatted table, adds per-process owner, PID, and command columns directly, and exposes the result as JSON so it can be consumed by scripts rather than by eyes. It replaces nvidia-smi as the routine query command a user or operator runs when they need to know which GPUs are free and who is using them, while still sitting on top of the same driver-level source of truth.

Key capabilities

• Compact colorized GPU table as the default gpustat output, with --color to force color when stdout is not a tty and --no-color to suppress it.
• Per-process attribution through -u / --show-user, -c / --show-cmd, -f / --show-full-cmd, and -p / --show-pid, or --no-processes to hide process information entirely.
• Hardware detail flags: -F / --show-fan for fan speed, -e / --show-codec for encoder and decoder utilization, and -P / --show-power for power draw and limit.
• -a / --show-all to display every GPU property above at once, and --id 0,1,2 to target a specific subset of GPUs by index.
• Watch mode via --watch, -i, and --interval, which polls and refreshes the display on a set interval.
• --json for machine-readable output, plus a Python API where gpustat.new_query() returns a GPUStatCollection supporting .print_formatted() and .jsonify().
• Shell completion generation with --print-completion (bash|zsh|tcsh), and --debug for diagnosing query failures.

Who uses it and how

• Shared multi-GPU workstations and lab servers, where the --show-user and --show-pid flags let one person find out which colleague is holding memory on a device.
• Cluster and operations work, where watch mode (gpustat --watch or gpustat -i) runs in a terminal pane for continuous polling instead of repeatedly invoking nvidia-smi.
• Automation and monitoring pipelines, where gpustat --json feeds a dashboard or scheduler, or where the Python API is imported to log GPU state from inside a training job.
• Administrators who need a narrow view: --id restricts the query to chosen devices, and --no-processes trims the output when process detail is not wanted.
• Teams that prefer a browser view, via gpustat-web, a web interface of gpustat that is available in alpha.

Getting started

Install from PyPI with pip install gpustat, or use pip install --user gpustat when root privileges are unavailable; the master branch can be installed with pip install git+https://github.com/wookayin/gpustat.git@master. The dependency is nvidia-ml-py, NVIDIA's official Python binding for NVML — not the pynvml package, which will not work.

How it compares

Among similar tools, gpustat positions itself explicitly as "just less than nvidia-smi": it does not replace nvidia-smi but condenses its output into a more legible form, and it depends on the same NVIDIA driver and NVML layer underneath. Its companion gpustat-web extends the same querying into a browser interface, currently in alpha, for users who want the data outside a terminal.

When to use it — and when not to

A self-hoster or user needs a working NVIDIA driver — version 450.00 or higher for gpustat 1.0+ — and the correct nvidia-ml-py binding, and Python 3.6 or newer; matching CUDA_DEVICE_ORDER=PCI_BUS_ID is required if CUDA and gpustat are to report the same GPU indices. It is not a fit for AMD hardware, since the README states it works with NVIDIA graphics devices only and there is no AMD support as of now. Anyone needing vendor-neutral GPU monitoring, or a web dashboard that is not alpha-quality, should look elsewhere or wait.

pip install gpustat

pip install git+https://github.com/wookayin/gpustat.git@master

import gpustat

stats = gpustat.new_query()   # a GPUStatCollection
stats.print_formatted()       # same output as the `gpustat` command

data = stats.jsonify()        # query result as a dict (same as `gpustat --json`)

[0] GeForce GTX Titan X | 77°C,  96 % | 11848 / 12287 MB | python/52046(11821M)