NVIDIA Management Library Python Bindings (Python 3 Port)

Warnings

• breaking The `nvidia-ml-py3` package is officially deprecated and its GitHub repository is archived. Users are strongly advised to switch to the actively maintained `nvidia-ml-py` package (note the lack of '3' in the name) for continued support and updates.
  Fix: Migrate to `pip install nvidia-ml-py` and update imports accordingly (e.g., `from pynvml import *` will still work, but check for any API changes).
• gotcha NVML functionality critically depends on a correctly installed and up-to-date NVIDIA GPU driver. Issues like 'NVML not initialized' or 'NVMLError: Driver Not Loaded' typically indicate driver problems, missing driver files, or insufficient user permissions to access GPU devices.
  Fix: Ensure NVIDIA drivers are installed and compatible with your GPU and OS. Verify the GPU is recognized (e.g., `nvidia-smi` command-line tool). Grant necessary permissions if running as a restricted user. Reinstalling NVIDIA drivers or the NVML libraries might be necessary.
• gotcha It is essential to call `pynvml.nvmlInit()` before any other NVML functions and `pynvml.nvmlShutdown()` when your application finishes. Failing to call `nvmlInit()` will result in `NVMLError: Uninitialized`, and not calling `nvmlShutdown()` can lead to resource leaks.
  Fix: Always wrap NVML calls within a `try...finally` block to ensure `nvmlInit()` and `nvmlShutdown()` are called reliably, as shown in the quickstart example.
• breaking The underlying `nvidia-ml-py` (and thus `nvidia-ml-py3`) has historically introduced backward-incompatible API changes, particularly concerning data structures like `nvmlProcessInfo_t`. Newer versions might introduce fields (e.g., `gpuInstanceId`, `computeInstanceId`) that are incompatible with older NVIDIA drivers, causing crashes or incorrect data.
  Fix: Pin the library version (e.g., `nvidia-ml-py==X.Y.Z`) that is compatible with your specific NVIDIA driver version. Refer to the `nvidia-ml-py` release history for compatibility notes.
• gotcha Some constant definitions in `pynvml.py` (e.g., `NVML_P2P_CAPS_INDEX_READ`, `NVML_GRID_LICENSE_EXPIRY_` definitions) have been reported to contain extraneous commas, inadvertently turning them into tuples instead of integers. This can cause unexpected type errors if used directly.
  Fix: Inspect the `pynvml.py` source for the exact constant definition if encountering type errors. If present, manually extract the integer value from the tuple or switch to a fixed version of the `nvidia-ml-py` library if available.

Install

• pip install nvidia-ml-py3 PyPI

Imports

• pynvml

  import pynvml

  The package name on PyPI is `nvidia-ml-py3`, but the internal module to import is `pynvml`.

Quickstart

Initializes the NVML library, retrieves the system's NVIDIA driver version, iterates through detected GPUs to display their name, temperature, and memory usage, and then properly shuts down the NVML library. Includes error handling for common NVML issues.

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)
        name = pynvml.nvmlDeviceGetName(handle)
        temperature = pynvml.nvmlDeviceGetTemperature(handle, pynvml.NVML_TEMPERATURE_GPU)
        memory_info = pynvml.nvmlDeviceGetMemoryInfo(handle)
        print(f"  Device {i}: {name.decode('utf-8') if isinstance(name, bytes) else name}")
        print(f"    Temperature: {temperature}°C")
        print(f"    Memory: {memory_info.used >> 20}MiB / {memory_info.total >> 20}MiB (Used/Total)")

except pynvml.NVMLError as error:
    print(f"NVML Error: {error}")
    print("Common causes: Missing/outdated NVIDIA drivers, permission issues, or no GPUs found.")
finally:
    try:
        pynvml.nvmlShutdown()
    except pynvml.NVMLError as error:
        print(f"NVML Shutdown Error: {error}")