CUDA Pathfinder

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