cuda.pathfinder.load_nvidia_dynamic_lib

cuda.pathfinder.load_nvidia_dynamic_lib(

libname: str,

) → LoadedDL

Load an NVIDIA dynamic library by name.

Parameters:

libname (str) – The short name of the library to load (e.g., "cudart", "nvvm", etc.).

Returns:

Object containing the OS library handle and absolute path.

Important:

Never close the returned handle. Do not call dlclose (Linux) or FreeLibrary (Windows) on the LoadedDL._handle_uint.

Why: the return value is cached (functools.cache) and shared across the process. Closing the handle can unload the module while other code still uses it, leading to crashes or subtle failures.

This applies to Linux and Windows. For context, see issue #1011: NVIDIA/cuda-python#1011

Return type:

LoadedDL

Raises:

• DynamicLibUnknownError – If libname is not a recognized library name.

• DynamicLibNotAvailableError – If libname is recognized but not supported on this platform.

• DynamicLibNotFoundError – If the library cannot be found or loaded.

• RuntimeError – If Python is not 64-bit.

Windows on ARM (WoA) Note:

On Windows, this API aims to load a dynamic library whose architecture matches the Python interpreter architecture. For example, x64 Python running on an Arm64 machine targets an x64 DLL, while native Arm64 Python targets an Arm64 DLL. A library loaded into the Python process must be compatible with that process. This differs from find_nvidia_binary_utility, which targets the native machine architecture when selecting architecture-specific executables.

Search order:

0. Already loaded in the current process

   • If a matching library is already loaded by some other component, return its absolute path and handle and skip the rest of the search.

1. NVIDIA Python wheels

   • Scan installed distributions (site-packages) to find libraries shipped in NVIDIA wheels.

2. Conda environment

   • Conda installations are discovered via CONDA_PREFIX, which is defined automatically in activated conda environments (see https://docs.conda.io/projects/conda-build/en/stable/user-guide/environment-variables.html).

3. OS default mechanisms

   • Fall back to the native loader:

     • Linux: dlopen(). CUDA Toolkit (CTK) system installs may be discovered via LD_LIBRARY_PATH or linker configuration such as /etc/ld.so.conf.d/*cuda*.conf.

     • Windows: LoadLibraryExW(dll_name, NULL, 0). For an ordinary unpackaged process, native DLL search includes PATH unless a different process DLL search policy has been configured. Python’s restricted defaults for its own loads do not override this native call.

4. Environment variables

   • First search library-specific roots declared by the descriptor, such as CUDNN_PATH and NCCL_HOME, using their platform-specific product layouts. Then use CUDA_PATH or CUDA_HOME (in that order). These are fallback discovery locations, not runtime toolkit selectors: libraries found by earlier steps take precedence. On Windows, the NVIDIA CTK installer automatically adds CUDA_PATH to the system-wide environment.

5. Windows Program Files (configured libraries only)

   • Search descriptor-configured standalone installation roots, such as versioned x64 cuDNN directories under ProgramFiles, using the general per-library anchor layout.

6. CTK root canary probe (discoverable libs only)

   • For selected libraries whose shared object doesn’t reside on the standard linker path (such as nvvm and cupti), attempt to derive CTK root by system-loading a well-known CTK canary library in a subprocess and then searching relative to that root. On Windows, the canary uses the same native LoadLibraryExW(..., 0) semantics as step 3, so it can discover libraries through PATH subject to the child process’s DLL search policy.

Driver libraries ("cuda", "nvml"):

These are part of the NVIDIA display driver (not the CUDA Toolkit) and are expected to be reachable via the native OS loader path. For these libraries the search is simplified to:

0. Already loaded in the current process

1. OS default mechanisms (dlopen / LoadLibraryExW)

The non-driver steps (site-packages, conda, environment roots, ProgramFiles, and canary probe) are skipped entirely.

Notes

The search is performed per library. There is currently no mechanism to guarantee that multiple libraries are all resolved from the same location.