# gpustat: a compact nvidia-smi for GPU status from the terminal

> gpustat wraps NVIDIA's NVML bindings in a one-line-per-GPU command and a small Python API. It is useful for shared GPU hosts and quick checks, but it is NVIDIA-only and its install path has one common trap.

**wookayin/gpustat** — 📊 A simple command-line utility for querying and monitoring GPU status

- Repository: https://github.com/wookayin/gpustat
- Website: https://pypi.python.org/pypi/gpustat
- Stars: 4,391 · Forks: 284
- Language: Python
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/wookayin-gpustat

## What gpustat does that nvidia-smi does not, and who it is for

nvidia-smi prints a lot. gpustat prints one line per GPU. The README frames the project as "Just less than nvidia-smi?" and the default output is a single row: index, GPU name, temperature, utilization, memory used over total, and the running processes with their memory. That density is the whole product. On a shared training box you can read six GPUs in six lines and see which colleague's python process is holding 11 GB.

The audience is narrow and clear. It is for people who already have NVIDIA hardware and a working driver, who live in a terminal, and who want either a human-readable status line or a machine-readable one. The Python API extends that to code: gpustat.new_query() returns a GPUStatCollection, and stats.jsonify() gives the same dictionary as the --json flag. A scheduler, a notebook, or a chat bot can call that instead of parsing nvidia-smi text.

It is not a monitoring system. There is no daemon in this repository, no history, no alerting, and no web UI. The README points at gpustat-web as a separate alpha project, and that separation matters: everything here is a point-in-time query.

## How the query path works: NVML, pynvml, and the process list

gpustat does not shell out to nvidia-smi. It talks to NVML through NVIDIA's official Python binding, nvidia-ml-py. That binding is the mechanism the README is most emphatic about, because there is a name collision in the ecosystem: a PyPI package literally called pynvml also exists, and the README warns in bold not to install it or list it as a dependency. The correct package is nvidia-ml-py.

Version coupling follows from that. gpustat 1.2 and later require nvidia-ml-py >= 12.535.108. gpustat 1.0 and later require NVIDIA Driver 450.00 or higher and nvidia-ml-py >= 11.450.129. If the driver is older, the README's answer is to install an older gpustat, specifically pip install gpustat<1.0, and it links issue 107 for the details.

The data flow is therefore: your Python process imports the NVML binding, enumerates devices, reads temperature, utilization, memory, and the compute process list, then formats it. Because the process list comes from NVML rather than from parsing nvidia-smi output, the columns for user, command, and PID are assembled in gpustat itself, which is why flags like -u, -c, and -p exist as display switches rather than as different queries. One consequence worth knowing: the GPU index shown is the PCI bus ID, and CUDA orders devices differently by default. The README's fix is to export CUDA_DEVICE_ORDER=PCI_BUS_ID before setting CUDA_VISIBLE_DEVICES, otherwise the GPU you think is 0 may not be the one CUDA picks.

## Installing gpustat and a first real use

The README gives a single install command, with a user-namespace variant for machines where you lack sudo.

```bash
pip install gpustat
```

If you are not root, the documented alternative is pip install --user gpustat. For the master branch rather than a release, the README shows pip install git+https://github.com/wookayin/gpustat.git@master. There is no conda instruction in the README, and no distro package is named there, so treat pip as the supported path.

Before the first run, confirm the binding. The README states that gpustat 1.2+ needs nvidia-ml-py >= 12.535.108 and that installing the package named pynvml will not work.

```bash
pip install nvidia-ml-py
```

Then run it plain. On a machine with two visible GPUs you should see two lines, each starting with a bracketed index, followed by the GPU name, temperature, utilization, used and total memory, and any processes.

```bash
gpustat
```

The flags that earn their keep on a shared host are the display switches. -u adds the process owner, -c the command name, -p the PID, and -a turns on everything the tool can show. To watch continuously, the README documents --watch and -i/--interval as equivalent to running watch gpustat, and notes that on older versions you would use watch --color -n1.0 gpustat --color instead.

```bash
gpustat --watch
```

For scripting, --json emits the same data as a dictionary, and the Python API is a three-line substitution.

```python
import gpustat

stats = gpustat.new_query()
stats.print_formatted()
data = stats.jsonify()
```

If something fails, the README's first suggestion is gpustat --debug. Two further options exist for specific needs: --id 0,1,2 restricts the query to chosen indices, and --no-processes drops the process section entirely. Shell completion can be printed with --print-completion bash, zsh, or tcsh.

## The NVIDIA-only boundary and other cases where gpustat is the wrong tool

The README states the hardware limit without hedging: this works with NVIDIA Graphics Devices only, no AMD support as of now. If your fleet is mixed or AMD-based, gpustat cannot answer the question at all, and no flag changes that.

There are softer limits too. The tool reports the present moment, so a process that spiked and exited between two invocations is invisible; there is no retention layer in this repository. The process list is also only as complete as NVML's view of compute processes, and gpustat's own display options are the only lens you get on it. On a busy node where you want to know who held memory an hour ago, gpustat is the wrong instrument.

Performance is a real consideration on large hosts. The README notes that running nvidia-smi daemon with root privileges makes querying GPUs much faster and less CPU-hungry, which implies the default query path is not free. A tight --watch interval on a machine with many GPUs will cost you, and the README's own remedy points outside gpustat, at an nvidia-smi daemon you must run yourself.

Finally, packaging. The repository uses setuptools_scm, and setup.py raises an ImportError telling you that setuptools_scm needs to be installed manually if you run setup.py directly, or that you should consider pip install -e . instead. Building from a git checkout without that tool will fail, and the README does not document a rollback procedure for a bad upgrade beyond pinning an older version such as gpustat<1.0 for old drivers.

## gpustat, nvtop, and nvitop: different shapes of the same job

The most direct alternative in the search results is nvtop, and the difference is interface class rather than feature list. nvtop is an interactive terminal application; gpustat prints lines and exits, or repeats them under --watch. If you want to scroll, sort, and poke at a live view with a keyboard, an interactive monitor is the better fit. If you want output you can pipe into grep, cut, or a JSON parser, gpustat's line and --json formats are the point.

nvitop is the other comparison people search for, and the honest statement is that the README does not describe nvitop's internals, so the comparison I can defend is only about form: gpustat is a query command plus a small library, and its README advertises gpustat-web as a separate alpha web interface rather than bundling one. Anything beyond that would be guesswork.

The comparison with nvidia-smi is the one the README itself invites. nvidia-smi is the vendor tool and is the thing gpustat queries underneath through NVML; gpustat trades its breadth for a compact default view and a stable JSON shape. If you need the full set of vendor counters, or you are on a machine where Python packaging is unwelcome, nvidia-smi already ships with the driver and requires no install. That is a genuine advantage, not a consolation prize.

## Maintenance, licence, and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-15, so work is happening on master. That said, the release cadence visible in the release list is slower than the commit activity: the most recent tagged release is v1.1.1 from 2023-08-22, preceded by v1.1 in April 2023 and v1.0 in September 2022. If you install from PyPI you are getting a release that predates the current master branch, and if you want the newest behaviour the README's own instruction is pip install git+https://github.com/wookayin/gpustat.git@master. Those are two different artifacts, and pinning matters.

Upgrade cost concentrates in the dependency chain rather than in gpustat's own surface. Moving to gpustat 1.0+ raises the driver floor to 450.00 and the binding floor to nvidia-ml-py >= 11.450.129; gpustat 1.2+ raises the binding floor again to >= 12.535.108. Python requirements also moved: gpustat 1.0 needs Python >= 3.4, gpustat 1.1 needs >= 3.6, and gpustat 1.2+ is documented as tested through Python 3.16 development builds. On a cluster with an old driver, the upgrade path is downward, not upward.

Licensing is MIT, per the LICENSE file and the badge in the README. That is permissive and imposes no copyleft obligation on your own code, but it also means no warranty and no support commitment from the author. This is a description of the licence text, not legal advice; if your organisation has rules about which licences may enter a product, run the MIT terms past whoever owns that policy.

## Conclusion

Adopt gpustat on NVIDIA machines where you want a compact per-GPU line, JSON for scripts, or gpustat.new_query() inside Python. Do not adopt it for AMD or non-NVIDIA hardware, for a persistent web dashboard (that is a separate alpha project), or if you need per-process history. Verify first that your driver is 450.00 or higher for gpustat 1.0+, that you install nvidia-ml-py rather than pynvml, and that CUDA_DEVICE_ORDER=PCI_BUS_ID is set if you compare its indices against CUDA.

## FAQ

### How do I install gpustat?

The README gives one command, pip install gpustat, with pip install --user gpustat for machines where you lack root. For the latest master branch it shows pip install git+https://github.com/wookayin/gpustat.git@master.

### What is the difference between gpustat and nvidia-smi?

gpustat queries GPUs through NVIDIA's NVML Python binding rather than calling nvidia-smi, and it prints one compact line per GPU by default. nvidia-smi ships with the driver and covers a broader set of vendor counters, while gpustat adds flags such as -u, -c, -p, --json, and a small Python API.

### How can I check my GPU status in Linux with gpustat?

Run gpustat with no arguments to get one line per GPU showing index, name, temperature, utilization, memory used and total, and running processes. Add -u, -c, and -p for the process owner, command name, and PID, or use -i/--watch to refresh on an interval.

### How can I see what is causing GPU usage with gpustat?

The process section of each line lists running processes with their GPU memory usage, and the -u, -c, and -p flags add owner, command name, and PID. The README notes that --no-processes removes this section, so leave it off if you want to see who is using the GPU.

### What are the differences between nvitop and nvtop?

The README does not describe nvitop or nvtop, so this material cannot answer the comparison. What it does say is that gpustat itself is a query command with a Python API, and that a web interface exists as the separate alpha project gpustat-web.

## Sources

- [License: MIT](https://github.com/wookayin/gpustat/blob/master/LICENSE)
- [Project website](https://pypi.python.org/pypi/gpustat)
- [README](https://github.com/wookayin/gpustat/blob/master/README.md)
- [Releases](https://github.com/wookayin/gpustat/releases)
- [wookayin/gpustat on GitHub](https://github.com/wookayin/gpustat)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wookayin-gpustat