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:

• 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: LoadLibraryW()

   • CUDA Toolkit (CTK) system installs with system config updates are often discovered via:

     • Linux: /etc/ld.so.conf.d/*cuda*.conf

     • Windows: C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\vX.Y\bin on the system PATH.

4. Environment variables

   • If set, use CUDA_HOME or CUDA_PATH (in that order).

Notes

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