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.

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()

     • Windows: LoadLibraryExW()

     On Linux, CUDA Toolkit (CTK) system installs with system config updates are usually discovered via /etc/ld.so.conf.d/*cuda*.conf.

     On Windows, under Python 3.8+, CPython configures the process with SetDefaultDllDirectories(LOAD_LIBRARY_SEARCH_DEFAULT_DIRS). As a result, the native DLL search used here does not include the system PATH.

4. Environment variables

   • If set, use CUDA_HOME or CUDA_PATH (in that order). On Windows, this is the typical way system-installed CTK DLLs are located. Note that the NVIDIA CTK installer automatically adds CUDA_PATH to the system-wide environment.

5. CTK root canary probe (discoverable libs only)

   • For selected libraries whose shared object doesn’t reside on the standard linker path (currently nvvm), 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 semantics as step 3, so there is also no PATH-based discovery.

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 CTK-specific steps (site-packages, conda, CUDA_HOME, 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.