cuda.pathfinder API Reference#

The cuda.pathfinder module provides utilities for loading NVIDIA dynamic libraries, and experimental APIs for locating NVIDIA C/C++ header directories.

SUPPORTED_NVIDIA_LIBNAMES

Built-in immutable sequence.

load_nvidia_dynamic_lib(libname)

Load an NVIDIA dynamic library by name.

LoadedDL(abs_path, ...)

DynamicLibNotFoundError

SUPPORTED_HEADERS_CTK

Mapping from short CUDA Toolkit (CTK) library names to their canonical header basenames (used to validate a discovered include directory).

find_nvidia_header_directory(libname)

Locate the header directory for a supported NVIDIA library.

Environment Variable Utilities#

The cuda.pathfinder._utils.env_vars module provides centralized handling of CUDA environment variables used across all cuda-python packages.

_utils.env_vars.get_cuda_home_or_path()

Get CUDA Toolkit path from environment variables.

_utils.env_vars.CUDA_ENV_VARS_ORDERED

Canonical search order for CUDA Toolkit environment variables.
cuda.pathfinder._utils.env_vars.get_cuda_home_or_path() → str | None#

Get CUDA Toolkit path from environment variables.

Returns the value of CUDA_PATH or CUDA_HOME following the canonical search order defined in CUDA_ENV_VARS_ORDERED. If both are set and differ, CUDA_PATH takes precedence and a warning is issued.

The result is cached for the process lifetime. The first call determines the CUDA Toolkit path, and subsequent calls return the cached value.

Returns:

Path to CUDA Toolkit, or None if neither variable is set. Empty strings are preserved and returned as-is if explicitly set in the environment.

Warning

UserWarning: If multiple CUDA environment variables are set but point to

different locations (only on the first call).

See also

CUDA_ENV_VARS_ORDERED: The canonical search order for CUDA environment variables.

cuda.pathfinder._utils.env_vars.CUDA_ENV_VARS_ORDERED = ('CUDA_PATH', 'CUDA_HOME')#

Canonical search order for CUDA Toolkit environment variables.

This tuple defines the priority order used by get_cuda_home_or_path() and throughout cuda-python packages when determining which CUDA Toolkit to use.

The first variable in the tuple has the highest priority. If multiple variables are set and point to different locations, the first one is used and a warning is issued.

Note

Breaking Change in v1.4.0: The order changed from ("CUDA_HOME", "CUDA_PATH") to ("CUDA_PATH", "CUDA_HOME"), making CUDA_PATH the highest priority.

Type:

tuple[str, …]