Registry / ai-ml / cuda-pathfinder

cuda-pathfinder

JSON →
library1.5.0pypypi✓ verified 52d ago

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.

ai-mldevops
pip install cuda-pathfinder
Install & Compatibility
Where this runs
tested against v1.5.5 · 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.103.925 runs
installs and imports cleanly · install 0.0s · import 0.128s · 18.2MB
glibc
py 3.103.925 runs
installs and imports cleanly · install 1.6s · import 0.122s · 19MB
16MB installed
● package 16MB
Code
Verified usage

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

load_nvidia_dynamic_lib
from cuda.pathfinder import load_nvidia_dynamic_lib
find_nvidia_header_directory
from cuda.pathfinder import find_nvidia_header_directory

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}")
Debug
Known issues
gotchaDo 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.
affects: All versions
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.
affects: All versions
gotchaMisconfigured 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.
affects: All versions
breakingThe `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.
affects: Versions 1.4.0 and later, relative to older `cuda-python` structures
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cuda.pathfinder'
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
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
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
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.
Upgrade
Version history
1.5.5latest on PyPI
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
Agent activity
19 hits · last 30 days
node
4
mj12bot
3
ahrefsbot
3
seranking-bot
3
amazonbot
1
chatgpt-user
1
Resources