Python Utilities for the NVIDIA Management Library

Warnings

• breaking The `pynvml` project (gpuopenanalytics/pynvml) and its `pynvml_utils` module are officially deprecated as of version 13.0.1. Users are strongly advised to transition to using the `nvidia-ml-py` package directly for future development and stability.
  Fix: Migrate your project to install and use `nvidia-ml-py` directly. While `pynvml` currently wraps `nvidia-ml-py`, relying on the deprecated wrapper is not recommended for long-term projects.
• gotcha The NVIDIA Management Library (NVML) must be explicitly initialized with `pynvml.nvmlInit()` and shut down with `pynvml.nvmlShutdown()`. Failing to call `nvmlShutdown()` can lead to resource leaks and prevent subsequent NVML operations.
  Fix: Always wrap your NVML operations within a `try...finally` block to ensure `pynvml.nvmlShutdown()` is called, even if errors occur. Check for `NVMLError_Uninitialized` on shutdown if `nvmlInit()` might have failed.
• gotcha The `nvidia-ml-py` library (which `pynvml` now wraps) has a history of breaking backward compatibility with often uncomprehensive changelogs, making migrations challenging.
  Fix: Pin your `nvidia-ml-py` dependency to a specific minor version in your `requirements.txt` or `pyproject.toml` to avoid unexpected breaking changes with new releases. Thoroughly test updates before deploying to production.
• gotcha Many NVML functions require elevated privileges (e.g., admin/root) to query certain GPU performance counters or to modify GPU settings. Running without sufficient permissions can result in `NVMLError` exceptions.
  Fix: Ensure your application or script has the necessary system permissions to access NVML features. Consult NVIDIA's NVML documentation for specific privilege requirements for each function. Implement robust error handling (e.g., `try...except pynvml.NVMLError_NotPermitted`) to gracefully manage permission issues.
• gotcha NVML functions in `pynvml` do not return error codes directly but instead raise Python exceptions (specifically `pynvml.NVMLError` and its subclasses) for failures.
  Fix: Wrap calls to `pynvml` functions in `try...except pynvml.NVMLError as error:` blocks to catch and handle errors appropriately. Check the specific `NVMLError` subclass for detailed error information (e.g., `NVMLError_DriverNotLoaded`, `NVMLError_Uninitialized`).

Install

• pip install pynvml Install latest pynvml

Imports

• pynvml

  import pynvml

  Even though the `pynvml` project is deprecated, the installed `pynvml` package (which wraps `nvidia-ml-py`) still provides the NVML bindings via the `pynvml` module.

Quickstart

This quickstart demonstrates how to initialize NVML, query the number of available GPUs, retrieve device-specific information (name, memory, temperature), and properly shut down the NVML library. Error handling for common NVML issues is included.

import pynvml

try:
    pynvml.nvmlInit()
    print(f"Driver Version: {pynvml.nvmlSystemGetDriverVersion()}")

    device_count = pynvml.nvmlDeviceGetCount()
    print(f"Found {device_count} GPU device(s).")

    for i in range(device_count):
        handle = pynvml.nvmlDeviceGetHandleByIndex(i)
        device_name = pynvml.nvmlDeviceGetName(handle)
        memory_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
        temperature = pynvml.nvmlDeviceGetTemperature(handle, pynvml.NVML_TEMPERATURE_GPU)

        print(f"\nDevice {i} ({device_name.decode('utf-8')}):")
        print(f"  Total Memory: {memory_info.total / (1024**3):.2f} GB")
        print(f"  Used Memory: {memory_info.used / (1024**3):.2f} GB")
        print(f"  Free Memory: {memory_info.free / (1024**3):.2f} GB")
        print(f"  GPU Temperature: {temperature}°C")

except pynvml.NVMLError as error:
    print(f"NVML Error: {error}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    try:
        pynvml.nvmlShutdown()
    except pynvml.NVMLError_Uninitialized:
        pass # NVML was not initialized or already shut down