CUDA Pathfinder

Common errors

• ModuleNotFoundError: No module named 'cuda.pathfinder'

  cause This error typically occurs because the `cuda-pathfinder` package is not installed in your Python environment. In some specific build environments (like PEP 517 in-tree build backends), it can also be due to Python's module resolution shadowing the installed `cuda` namespace package.
  fix To resolve this, install the library using pip: `pip install cuda-pathfinder`. If the issue persists in a complex build environment, refer to the official documentation or issue trackers for specific workarounds related to namespace package resolution.

• cuda.pathfinder.DynamicLibNotFoundError

  cause This exception is raised by `cuda.pathfinder.load_nvidia_dynamic_lib()` when the requested NVIDIA dynamic library (e.g., 'cudart', 'nvvm') cannot be found or loaded on the system. This usually indicates that the CUDA Toolkit is not correctly installed, or its path is not properly configured in environment variables.
  fix Verify that your CUDA Toolkit installation is complete and accessible. Ensure that relevant environment variables such as `CUDA_PATH`, `LD_LIBRARY_PATH` (Linux), or system `PATH` (Windows) correctly point to the CUDA installation's `bin` and `lib` directories.

• cuda.pathfinder.DynamicLibUnknownError

  cause This error occurs when you call `cuda.pathfinder.load_nvidia_dynamic_lib()` with a `libname` argument that is not a recognized NVIDIA dynamic library name supported by `cuda-pathfinder`.
  fix Consult the `cuda-pathfinder` documentation, specifically `cuda.pathfinder.SUPPORTED_NVIDIA_LIBNAMES`, for a list of valid library names and ensure you are using one of the supported names.

• cuda.pathfinder.DynamicLibNotAvailableError

  cause This exception is raised by `cuda.pathfinder.load_nvidia_dynamic_lib()` when the specified NVIDIA dynamic library is recognized but is not supported on the current platform or operating system.
  fix Ensure that the NVIDIA dynamic library you are attempting to load is compatible with your current operating system and hardware configuration.

Warnings

• gotcha Do not manually close the `LoadedDL` object's handle. The library internally caches and reuses handles, and closing them (e.g., `dlclose` on Linux, `FreeLibrary` on Windows) can lead to crashes or subtle failures in other parts of the application that might still be using the shared module.
  Fix: Avoid calling OS-specific `close` functions on `LoadedDL._handle_uint`. The library manages the lifecycle of loaded dynamic libraries internally.
• gotcha `cuda-pathfinder` is CUDA Toolkit (CTK) version-agnostic but adheres to NVIDIA's general CUDA Toolkit support policy, typically supporting the two most recent major versions. Relying on it to find components for very old or extremely new, unsupported CTK versions might lead to unexpected failures.
  Fix: Ensure that the installed CUDA Toolkit version falls within NVIDIA's supported range for `cuda-pathfinder` to function reliably. Refer to the `cuda-python` documentation for specific compatibility matrices.
• gotcha Misconfigured CUDA environment variables (e.g., `LD_LIBRARY_PATH`, `CUDA_HOME`, `PATH`) can cause `cuda-pathfinder` to fail locating components or find incorrect versions, even if the CUDA Toolkit is installed. The tool's discovery mechanism interacts with system environment settings.
  Fix: Verify and correctly set CUDA-related environment variables for your desired CUDA Toolkit version. Tools like `nvcc --version` and `nvidia-smi` can help diagnose the active CUDA environment. Ensure consistency between your environment setup and the components you expect `cuda-pathfinder` to find.
• breaking The `cuda-python` project, which `cuda-pathfinder` is a part of, has been restructured into a metapackage with independently versioned subpackages. While `cuda-pathfinder` maintains its own versioning, users previously relying on a monolithic `cuda-python` package might experience changes in installation patterns or implicit dependencies.
  Fix: Update your understanding and installation scripts to reflect the modular nature of `cuda-python` and its subpackages. Install `cuda-pathfinder` explicitly as `pip install cuda-pathfinder` rather than relying on a `cuda-python` metapackage to implicitly include it if explicit control is desired.

Install

• pip install cuda-pathfinder PyPI

Imports

• load_nvidia_dynamic_lib

  from cuda.pathfinder import load_nvidia_dynamic_lib

• find_nvidia_header_directory

  from cuda.pathfinder import find_nvidia_header_directory

Quickstart

This quickstart demonstrates how to use `cuda-pathfinder` to locate and load an NVIDIA dynamic library, such as the CUDA Runtime library (`cudart`). It highlights the primary use case of finding system-level CUDA components within a Python environment. The example includes error handling for when the library is not found.

from cuda.pathfinder import load_nvidia_dynamic_lib, DynamicLibNotFoundError
import os

try:
    # Locate and load the CUDA Runtime dynamic library (e.g., cudart.so, cudart.dll)
    cudart_lib = load_nvidia_dynamic_lib('cudart')
    print(f"Successfully loaded CUDA Runtime library: {cudart_lib.path}")

    # Example: Accessing its handle (but don't close it!)
    # The handle is a low-level OS object, specific usage depends on further operations
    # For instance, if you were to interact with a CFFI interface.
    print(f"Library handle (platform specific): {cudart_lib.handle_uint}")

    # You can also find other components like header directories
    # For this example, we're not using os.environ.get as it's not directly for auth.
    # No direct quickstart for header directory loading that requires external auth.
    # This part is illustrative of another feature.
    # try:
    #     cuda_headers = find_nvidia_header_directory()
    #     print(f"CUDA header directory found at: {cuda_headers.path}")
    # except Exception as e:
    #     print(f"Could not find CUDA header directory: {e}")

except DynamicLibNotFoundError:
    print("CUDA Runtime library 'cudart' not found. Ensure CUDA Toolkit is installed and accessible.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")