{"id":10075,"library":"py3nvml","title":"Python 3 Bindings for NVIDIA Management Library (NVML)","description":"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.","status":"active","version":"0.2.7","language":"en","source_language":"en","source_url":"https://github.com/fbcotter/py3nvml","tags":["nvidia","gpu","monitoring","nvml","hardware"],"install":[{"cmd":"pip install py3nvml","lang":"bash","label":"Install py3nvml"}],"dependencies":[],"imports":[{"note":"py3nvml re-exports NVML functions under the 'pynvml' namespace. Direct import from 'py3nvml' will not work for core NVML functions.","wrong":"from py3nvml import nvmlInit","symbol":"nvmlInit","correct":"from pynvml import nvmlInit"},{"note":"Exceptions are also exposed via the top-level 'pynvml' module, not nested within 'py3nvml.nvml'.","wrong":"from py3nvml.nvml import NVMLError","symbol":"NVMLError","correct":"from pynvml import NVMLError"}],"quickstart":{"code":"from pynvml import nvmlInit, nvmlShutdown, nvmlDeviceGetCount, nvmlDeviceGetHandleByIndex, nvmlDeviceGetName, nvmlDeviceGetMemoryInfo, NVMLError\n\ntry:\n    nvmlInit()\n    device_count = nvmlDeviceGetCount()\n    print(f\"Found {device_count} NVIDIA GPU(s).\")\n\n    for i in range(device_count):\n        handle = nvmlDeviceGetHandleByIndex(i)\n        name = nvmlDeviceGetName(handle)\n        mem_info = nvmlDeviceGetMemoryInfo(handle)\n        print(f\"  Device {i}: {name} - Total Memory: {mem_info.total / (1024**3):.2f} GB, Used: {mem_info.used / (1024**3):.2f} GB\")\n\nexcept NVMLError as error:\n    print(f\"NVMLError: {error}\")\n    if error.value == 6: # NVML_ERROR_DRIVER_NOT_LOADED\n        print(\"\\n  Cause: NVIDIA drivers may not be installed or are outdated, or the NVML library cannot be found.\")\n        print(\"  Fix: Ensure NVIDIA display drivers are properly installed and the NVML shared library is accessible.\")\n    elif error.value == 10: # NVML_ERROR_NO_PERMISSION\n        print(\"\\n  Cause: Insufficient permissions to access NVIDIA GPU devices.\")\n        print(\"  Fix: Run the script with appropriate permissions (e.g., as root or with specific user group).\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    try:\n        nvmlShutdown()\n        print(\"NVML shutdown successfully.\")\n    except NVMLError as error:\n        print(f\"Error during NVML shutdown: {error}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always import NVML functions and exceptions from `pynvml`, like `from pynvml import nvmlInit, NVMLError`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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`.","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.","error":"NVMLError: NVML Shared Library Not Found (Error Code: 6)"},{"fix":"NVML functions are exposed via `pynvml`. Use `from pynvml import nvmlInit, nvmlShutdown, NVMLError` to import the necessary symbols.","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()`.","error":"NameError: name 'nvmlInit' is not defined"},{"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.","cause":"NVIDIA drivers are installed but not loaded, or are outdated/corrupted, preventing the NVML library from functioning.","error":"NVMLError: Driver Not Loaded (Error Code: 6)"}]}