gpustat

library1.1.1pypypi✓ verified 24d ago

GPStat is a command-line utility for monitoring NVIDIA GPU status and usage, offering a more concise and user-friendly alternative to `nvidia-smi`. It provides essential GPU information including temperature, utilization, memory usage, and running processes. The library, currently at version 1.1.1, maintains an active development cycle with regular updates.

devops ai-ml observability

pip install gpustat

github ↗package ↗

INSTALL

IMPORT

SIG · GPUSTAT

gpustat

devopspythonv1.1.1

Install

4.5s avg

Import

709ms

Disk

24MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.740s · 28.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 4.5s · import 0.678s · 29MB

24MB installed

● package 24MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

new_query

✓ import gpustat gpus = gpustat.new_query()

The primary programmatic interface to get a collection of GPUStat objects.

GPUStat

✓ from gpustat.core import GPUStat

Represents status information for a single GPU. Typically obtained via `gpustat.new_query()`.

This quickstart demonstrates how to programmatically query NVIDIA GPU status using `gpustat.new_query()` to retrieve a collection of `GPUStat` objects and print their details. It also includes an example for getting JSON-formatted output.

import gpustat try: # Query GPU status gpus = gpustat.new_query() # Print formatted output for each GPU for gpu in gpus: print(f"GPU ID: {gpu.index}") print(f" Name: {gpu.name}") print(f" Temperature: {gpu.temperature}°C") print(f" Utilization: {gpu.utilization}% ") print(f" Memory Used: {gpu.memory_used}MB / {gpu.memory_total}MB") if gpu.processes: print(" Processes:") for p in gpu.processes: print(f" - PID: {p.pid}, Command: {p.command}, Memory: {p.gpu_memory_usage}MB") print("-" * 20) # Example: Get JSON output # import json # json_output = gpustat.new_query().jsonify() # print(json.dumps(json_output, indent=2)) except Exception as e: print(f"Could not query GPU status: {e}") print("Ensure NVIDIA drivers are installed and `nvidia-ml-py` is correctly configured.")

gpustat --version

Debug

Known issues

breakingPython 2 support was retired in `gpustat` v1.0. For versions 1.1 and higher, the minimum Python version required is 3.6.

fix

Upgrade your Python environment to 3.6 or newer. If Python 2 compatibility is essential, use `gpustat<1.0` (though this is not recommended due to lack of updates).

affects: >=1.0

breaking`gpustat` v1.0 and later utilize NVIDIA's official Python bindings (`nvidia-ml-py`) for NVML. This requires an NVIDIA driver version R450.00 or higher for correct display of process information. Older drivers may result in incomplete data.

fix

Upgrade your NVIDIA display driver to version R450.00 or newer. Ensure `nvidia-ml-py` is installed via `pip install nvidia-ml-py`.

affects: >=1.0

gotchaIt is explicitly advised *not* to install `pynvml` directly, as this will not work correctly with `gpustat`. Instead, the official NVIDIA bindings (`nvidia-ml-py`) should be used.

fix

Use `pip install nvidia-ml-py`. Avoid `pip install pynvml`.

affects: All versions using NVML bindings

gotchaGPU indexing in `gpustat` (and `nvidia-smi`) uses PCI Bus ID, which may differ from CUDA's default ordering. For consistent indexing between `gpustat` and CUDA applications, set the `CUDA_DEVICE_ORDER` environment variable.

fix

Before running CUDA programs, set `export CUDA_DEVICE_ORDER=PCI_BUS_ID`.

affects: All

Errors

Common errors & fixes

gpustat: command not found

The 'gpustat' command is not found in your system's PATH environment variable after installation, often occurring when installed via `pip install --user`.

fix

Ensure your user's local bin directory (e.g., `~/.local/bin` on Linux) is added to your PATH. You can often fix this by adding `export PATH=$PATH:$HOME/.local/bin` to your shell's configuration file (e.g., `.bashrc` or `.zshrc`) and then sourcing it.

ModuleNotFoundError: No module named 'gpustat'

The Python interpreter cannot find the 'gpustat' package, usually due to incorrect installation or the virtual environment not being activated.

fix

Make sure you have installed `gpustat` in the correct environment (e.g., `pip install gpustat`) and that the environment is activated. If installed globally, ensure the Python environment where it's installed is active.

pynvml.NVMLError_LibraryNotFound: NVML Shared Library Not Found

The NVIDIA Management Library (NVML), which `gpustat` uses via `pynvml`, cannot be found or loaded, often due to missing or incorrectly installed NVIDIA drivers, or a problem with `libnvidia-ml.so.1` (on Linux) or `nvml.dll` (on Windows).

fix

Verify that NVIDIA drivers are correctly installed and up-to-date, and that the NVML library is accessible. For Linux, ensure `libnvidia-ml.so.1` is in a standard library path (or linked correctly), and for Windows, ensure `nvml.dll` is in a discoverable location. Running `nvidia-smi` successfully is a good indicator of driver health. If the driver is too old, consider `pip install gpustat<1.0` or updating the driver.

AttributeError: module 'pynvml' has no attribute '_nvmlGetFunctionPointer'

This error typically occurs due to an incompatibility between the installed version of `gpustat` and the `nvidia-ml-py` (pynvml) library, where `gpustat` is trying to access an NVML function that is not present or has changed in the `nvidia-ml-py` version being used.

fix

Upgrade both `gpustat` and `nvidia-ml-py` to their latest compatible versions using `pip install --upgrade gpustat nvidia-ml-py` or downgrade `gpustat` to an older version (e.g., `gpustat==1.0.0`) if the driver/pynvml versions are fixed.

ModuleNotFoundError: No module named '_curses'

This error occurs when trying to use `gpustat` in watch mode (`gpustat -w` or `gpustat -i`) on systems where the `curses` library (a dependency for interactive terminal applications) is not installed.

fix

Install the `ncurses` development library for your system. On Debian/Ubuntu: `sudo apt-get install libncurses5-dev libncursesw5-dev`. On CentOS/Fedora: `sudo yum install ncurses-devel` or `sudo dnf install ncurses-devel`. Then reinstall/recreate your Python environment to link `_curses` correctly.

Upgrade

Version history

1.1.1latest on PyPI · released Aug 22, 2023

Audit

Dependencies

nvidia-ml-pyrequiredOfficial Python bindings for NVIDIA Management Library (NVML), essential for querying GPU status programmatically.

psutilrequiredUsed for retrieving process-level information running on the GPUs.

Agent activity

47 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/wookayin/gpustat ↗

packagehttps://pypi.org/project/gpustat/ ↗