nvidia-ml-py

library13.610.43pypypi✓ verified 22d ago

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.

ai-ml devops observability

pip install nvidia-ml-py

package ↗homepage ↗

INSTALL

IMPORT

SIG · NVIDIA-ML-PY

nvidia-ml-py

ai-mlpythonv13.610.43

Install

1.5s avg

Import

134ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v13.610.43 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.134s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.134s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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}")

Debug

Known issues

breakingThe 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`.

affects: All versions, particularly when upgrading drivers or CUDA toolkit.

gotchaNVML 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.

affects: All versions.

gotchaThere 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.

affects: All versions, especially for new users.

gotchaSome 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.

affects: Versions 11.525.131, 12.555.43, and potentially others.

gotchaSome 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.

affects: Potentially current and past versions.

Errors

Common errors & fixes

pynvml.nvmlInit() failed with error NVML_ERROR_DRIVER_NOT_LOADED

This error indicates that the NVIDIA graphics driver is either not installed, not loaded, or corrupted, preventing the NVML library from initializing and communicating with the GPU.

fix

Ensure NVIDIA drivers are correctly installed and loaded. On Linux, you might need to reboot or reinstall drivers. Verify `nvidia-smi` works. If running in a container, ensure the necessary driver volumes are mounted or that the container runtime (e.g., `nvidia-container-runtime`) is correctly configured.

NVML_ERROR_NOT_SUPPORTED

This error occurs when the requested NVML function is not supported by the current NVIDIA GPU hardware, the installed driver version, or the operating system. It can also appear with newer architectures like unified memory systems if the standard NVML queries are incompatible.

fix

Check if your GPU hardware supports the specific NVML feature you are trying to access. Update your NVIDIA drivers to the latest version. For very new hardware (like Grace Blackwell), there might be specific shim libraries or workarounds required.

ImportError: cannot import name 'nvml' from 'pynvml'

This `ImportError` typically happens when trying to import `nvml` directly from the `pynvml` package, which is not the correct module structure. The functions are usually accessed after `nvmlInit()` or via a handle. The package itself is `nvidia-ml-py` and its internal module is `pynvml`.

fix

The correct way to interact with NVML is usually through `pynvml` directly after importing it, for example: `from pynvml import *` or `import pynvml` and then calling functions like `pynvml.nvmlInit()`.

Driver/library version mismatch

This error happens when the `nvidia-ml-py` (or `pynvml`) Python binding version is incompatible with the installed NVIDIA driver version, often due to changes in NVML data structures between driver updates.

fix

Update your `nvidia-ml-py` library to a version compatible with your NVIDIA driver. For example, if you have a specific driver version (e.g., 535.104.05), you might need `nvidia-ml-py:12.535.78+`.

Upgrade

Version history

13.610.43latest on PyPI · released Jun 1, 2026

Audit

Dependencies

NVIDIA Driver (with NVML library)requirednvidia-ml-py is a wrapper around the NVML C library, which is part of the NVIDIA Linux graphics driver. A compatible driver must be installed on the system.

CUDA ToolkitoptionalNVML relies on CUDA, and a correctly configured CUDA installation is often necessary for full functionality.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/nvidia-ml-py/ ↗

homepagehttps://forums.developer.nvidia.com ↗