Python 3 Bindings for NVIDIA Management Library (NVML)

0.2.7 · active · verified Fri Apr 17

py3nvml provides Python 3 bindings for the NVIDIA Management Library (NVML), allowing users to monitor and manage NVIDIA GPUs. It's built on the original pynvml project but specifically targets Python 3. The current version is 0.2.7, and releases are infrequent, primarily for maintenance or compatibility updates.

Common errors

```
NVMLError: NVML Shared Library Not Found (Error Code: 6)
```
cause The NVIDIA Management Library (NVML) shared library (e.g., libnvidia-ml.so on Linux, nvml.dll on Windows) could not be located by the Python binding.

fix Ensure NVIDIA drivers are correctly installed. On Linux, verify that `libnvidia-ml.so` is present in a standard library path or specified in `LD_LIBRARY_PATH`. On Windows, ensure `nvml.dll` is in a directory listed in your system's PATH environment variable, or in `System32`.
```
NameError: name 'nvmlInit' is not defined
```
cause You attempted to call an NVML function without importing it from the correct namespace, likely trying `from py3nvml import ...` or `import py3nvml` and then `py3nvml.nvmlInit()`.

fix NVML functions are exposed via `pynvml`. Use `from pynvml import nvmlInit, nvmlShutdown, NVMLError` to import the necessary symbols.
```
NVMLError: Driver Not Loaded (Error Code: 6)
```
cause NVIDIA drivers are installed but not loaded, or are outdated/corrupted, preventing the NVML library from functioning.

fix Reboot your system. If the issue persists, reinstall or update your NVIDIA display drivers to the latest stable version compatible with your OS and hardware.

Warnings

gotcha py3nvml is a Python wrapper for the NVIDIA Management Library (NVML) C library. It requires NVIDIA drivers and the underlying NVML library to be correctly installed and accessible on your system. Without these, the Python library will raise errors such as `NVMLError_DriverNotLoaded` or `NVMLError_LibraryNotFound`.
Fix: Ensure you have up-to-date NVIDIA display drivers installed on your system. On Linux, ensure `libnvidia-ml.so` is in your `LD_LIBRARY_PATH`. On Windows, ensure `nvml.dll` is discoverable via your system's PATH.
gotcha Despite the package name `py3nvml`, the core NVML functions and exceptions are exposed through the `pynvml` namespace. Users often try to import directly from `py3nvml` (e.g., `from py3nvml import nvmlInit`), which will result in `NameError`.
Fix: Always import NVML functions and exceptions from `pynvml`, like `from pynvml import nvmlInit, NVMLError`.
gotcha NVML initialization (`nvmlInit()`) and shutdown (`nvmlShutdown()`) are crucial. Forgetting to call `nvmlShutdown()` can lead to resource leaks or unexpected behavior in long-running applications, although modern Python interpreters and OS often clean up on exit.
Fix: Always call `nvmlInit()` before making any other NVML calls and `nvmlShutdown()` when you are finished, ideally within a `try...finally` block to ensure shutdown even if errors occur.

Install

pip install py3nvml Install py3nvml

Imports

nvmlInit
wrong:
```
from py3nvml import nvmlInit
```
correct:
```
from pynvml import nvmlInit
```
py3nvml re-exports NVML functions under the 'pynvml' namespace. Direct import from 'py3nvml' will not work for core NVML functions.
NVMLError
wrong:
```
from py3nvml.nvml import NVMLError
```
correct:
```
from pynvml import NVMLError
```
Exceptions are also exposed via the top-level 'pynvml' module, not nested within 'py3nvml.nvml'.

Quickstart

This quickstart initializes NVML, queries the number of available NVIDIA GPUs, iterates through them to print their name and memory usage, and finally shuts down NVML. It includes basic error handling for common NVML issues.

from pynvml import nvmlInit, nvmlShutdown, nvmlDeviceGetCount, nvmlDeviceGetHandleByIndex, nvmlDeviceGetName, nvmlDeviceGetMemoryInfo, NVMLError

try:
    nvmlInit()
    device_count = nvmlDeviceGetCount()
    print(f"Found {device_count} NVIDIA GPU(s).")

    for i in range(device_count):
        handle = nvmlDeviceGetHandleByIndex(i)
        name = nvmlDeviceGetName(handle)
        mem_info = nvmlDeviceGetMemoryInfo(handle)
        print(f"  Device {i}: {name} - Total Memory: {mem_info.total / (1024**3):.2f} GB, Used: {mem_info.used / (1024**3):.2f} GB")

except NVMLError as error:
    print(f"NVMLError: {error}")
    if error.value == 6: # NVML_ERROR_DRIVER_NOT_LOADED
        print("\n  Cause: NVIDIA drivers may not be installed or are outdated, or the NVML library cannot be found.")
        print("  Fix: Ensure NVIDIA display drivers are properly installed and the NVML shared library is accessible.")
    elif error.value == 10: # NVML_ERROR_NO_PERMISSION
        print("\n  Cause: Insufficient permissions to access NVIDIA GPU devices.")
        print("  Fix: Run the script with appropriate permissions (e.g., as root or with specific user group).")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
finally:
    try:
        nvmlShutdown()
        print("NVML shutdown successfully.")
    except NVMLError as error:
        print(f"Error during NVML shutdown: {error}")

view raw JSON →