GPUStat: NVIDIA GPU Monitoring Utility

1.1.1 · active · verified Sat Apr 11

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.

Warnings

breaking Python 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).
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`.
gotcha It 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`.
gotcha GPU 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`.

Install

pip install gpustat Install latest version

Imports

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()`.

Quickstart

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.")

view raw JSON →