{"id":2962,"library":"gpustat","title":"GPUStat: NVIDIA GPU Monitoring Utility","description":"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.","status":"active","version":"1.1.1","language":"en","source_language":"en","source_url":"https://github.com/wookayin/gpustat","tags":["gpu","monitoring","nvidia","system","cli","nvml"],"install":[{"cmd":"pip install gpustat","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Official Python bindings for NVIDIA Management Library (NVML), essential for querying GPU status programmatically.","package":"nvidia-ml-py","optional":false},{"reason":"Used for retrieving process-level information running on the GPUs.","package":"psutil","optional":false}],"imports":[{"note":"The primary programmatic interface to get a collection of GPUStat objects.","symbol":"new_query","correct":"import gpustat\ngpus = gpustat.new_query()"},{"note":"Represents status information for a single GPU. Typically obtained via `gpustat.new_query()`.","symbol":"GPUStat","correct":"from gpustat.core import GPUStat"}],"quickstart":{"code":"import gpustat\n\ntry:\n    # Query GPU status\n    gpus = gpustat.new_query()\n\n    # Print formatted output for each GPU\n    for gpu in gpus:\n        print(f\"GPU ID: {gpu.index}\")\n        print(f\"  Name: {gpu.name}\")\n        print(f\"  Temperature: {gpu.temperature}°C\")\n        print(f\"  Utilization: {gpu.utilization}% \")\n        print(f\"  Memory Used: {gpu.memory_used}MB / {gpu.memory_total}MB\")\n        if gpu.processes:\n            print(\"  Processes:\")\n            for p in gpu.processes:\n                print(f\"    - PID: {p.pid}, Command: {p.command}, Memory: {p.gpu_memory_usage}MB\")\n        print(\"-\" * 20)\n\n    # Example: Get JSON output\n    # import json\n    # json_output = gpustat.new_query().jsonify()\n    # print(json.dumps(json_output, indent=2))\n\nexcept Exception as e:\n    print(f\"Could not query GPU status: {e}\")\n    print(\"Ensure NVIDIA drivers are installed and `nvidia-ml-py` is correctly configured.\")","lang":"python","description":"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."},"warnings":[{"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).","message":"Python 2 support was retired in `gpustat` v1.0. For versions 1.1 and higher, the minimum Python version required is 3.6.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Upgrade your NVIDIA display driver to version R450.00 or newer. Ensure `nvidia-ml-py` is installed via `pip install nvidia-ml-py`.","message":"`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.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Use `pip install nvidia-ml-py`. Avoid `pip install pynvml`.","message":"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.","severity":"gotcha","affected_versions":"All versions using NVML bindings"},{"fix":"Before running CUDA programs, set `export CUDA_DEVICE_ORDER=PCI_BUS_ID`.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}