NVIDIA Management Library Python Bindings

13.595.45 · active · verified Sun Apr 05

nvidia-ml-py provides official Python bindings for the NVIDIA Management Library (NVML), enabling programmatic access to NVIDIA GPU monitoring and management functions. It wraps the NVML C shared library, which is typically distributed with NVIDIA graphics drivers. The library is actively maintained with frequent updates, as indicated by its high versioning scheme.

Warnings

breaking The library often breaks backward compatibility without comprehensive changelogs. Changes to underlying NVML structures (e.g., `nvmlProcessInfo_t` with CUDA 11+) can cause `FunctionNotFound` errors or incorrect results with older NVIDIA drivers.
Fix: Refer to NVIDIA's NVML documentation for driver-specific API changes. Test thoroughly after driver/CUDA updates or library upgrades. Consider pinning specific `nvidia-ml-py` versions in your `requirements.txt`.
gotcha NVML initialization errors (`NVMLError_V1_UNINITIALIZED` or similar) are common due to outdated/missing NVIDIA drivers, misconfigured CUDA, permission issues, or conflicting driver versions.
Fix: Ensure NVIDIA drivers are up-to-date and compatible with your GPU. Verify CUDA toolkit installation. Check user permissions for GPU access. Restart Python kernel/script after making system changes. Consult NVIDIA's documentation for specific driver/NVML compatibility.
gotcha There can be confusion between `nvidia-ml-py` (official bindings) and other community-maintained packages like `pynvml` (which is deprecating its own bindings in favor of `nvidia-ml-py`) or the deprecated `nvidia-ml-py3`.
Fix: Always `pip install nvidia-ml-py` for the official, actively maintained bindings. Use `from pynvml import *` for imports, as `pynvml` is the module name within the `nvidia-ml-py` package.
gotcha Some constants within `pynvml.py` (e.g., `NVML_P2P_CAPS_INDEX_READ`) may be incorrectly defined as tuples instead of integers due to extraneous commas, leading to unexpected behavior.
Fix: Manually inspect the `pynvml.py` source for affected constants if you encounter type-related errors. If possible, upgrade to a version where this is known to be resolved, or implement workarounds in your code.
gotcha Some specific function bindings, such as `nvmlDeviceGetGpcClkMinMaxVfOffset` and `nvmlDeviceGetMemClkMinMaxVfOffset`, may incorrectly expect more parameters than required by the underlying C function, leading to argument errors.
Fix: Consult the exact function signature in the NVIDIA NVML C documentation and compare it with the Python binding's behavior. If an inconsistency is found, you might need to adjust your function call or be aware of potential issues.

Install

pip install nvidia-ml-py Install latest version

Imports

All NVML functions and constants
```
from pynvml import *
```
The primary way to import all exposed NVML functions and constants is to import everything from the 'pynvml' module, which is the internal module name used by nvidia-ml-py.

Quickstart

This quickstart demonstrates how to initialize NVML, retrieve the NVIDIA driver version, enumerate available GPUs, and query basic information like device name and memory usage. It includes error handling for NVML specific errors and ensures NVML is shut down properly.

from pynvml import *

try:
    nvmlInit()
    print(f"Driver Version: {nvmlSystemGetDriverVersion()}")
    deviceCount = nvmlDeviceGetCount()
    for i in range(deviceCount):
        handle = nvmlDeviceGetHandleByIndex(i)
        print(f"Device {i}: {nvmlDeviceGetName(handle)}")
        # Example: Get memory info
        info = nvmlDeviceGetMemoryInfo(handle)
        print(f"  Total Memory: {info.total / (1024**3):.2f} GB")
        print(f"  Used Memory: {info.used / (1024**3):.2f} GB")
        print(f"  Free Memory: {info.free / (1024**3):.2f} GB")
except NVMLError as error:
    print(f"NVML Error: {error}")
finally:
    try:
        nvmlShutdown()
    except NVMLError as error:
        print(f"NVML Shutdown Error: {error}")

view raw JSON →