CUDA Pathfinder

1.5.0 verified Tue May 12 auth: no python install: verified

cuda-pathfinder is a Python library from NVIDIA that provides utilities for locating CUDA components, such as dynamic libraries (.so, .dll) and CUDA Toolkit (CTK) header directories. It aims to be a one-stop solution for discovering CUDA artifacts within a Python environment. It is currently at version 1.5.0 and is part of the broader NVIDIA CUDA Python ecosystem, undergoing active development with regular releases.

pip install cuda-pathfinder

Common errors

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

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

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

error 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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.10s 18.2M

3.10 alpine (musl) - - 0.11s 18.2M

3.10 slim (glibc) wheel 1.5s 0.08s 19M

3.10 slim (glibc) - - 0.08s 19M

3.11 alpine (musl) wheel - 0.17s 20.1M

3.11 alpine (musl) - - 0.22s 20.1M

3.11 slim (glibc) wheel 1.7s 0.16s 21M

3.11 slim (glibc) - - 0.16s 21M

3.12 alpine (musl) wheel - 0.15s 11.9M

3.12 alpine (musl) - - 0.16s 11.9M

3.12 slim (glibc) wheel 1.5s 0.17s 12M

3.12 slim (glibc) - - 0.19s 12M

3.13 alpine (musl) wheel - 0.15s 11.7M

3.13 alpine (musl) - - 0.14s 11.6M

3.13 slim (glibc) wheel 1.5s 0.14s 12M

3.13 slim (glibc) - - 0.15s 12M

3.9 alpine (musl) wheel - 0.06s 17.5M

3.9 alpine (musl) - - 0.07s 17.5M

3.9 slim (glibc) wheel 1.8s 0.06s 18M

3.9 slim (glibc) - - 0.07s 18M

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 last tested: 2026-04-24

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