cuda.pathfinder.find_nvidia_binary_utility#

cuda.pathfinder.find_nvidia_binary_utility(utility_name: str) → str | None#

Locate a CUDA binary utility executable.

Parameters:

utility_name (str) – The name of the binary utility to find (e.g., "nvdisasm", "cuobjdump"). On Windows, the .exe extension will be automatically appended if not present. The function also recognizes .bat and .cmd files on Windows.

Returns:

Absolute path to the discovered executable, or None if the utility cannot be found. The returned path is normalized (absolute and with resolved separators).

Return type:

str or None

Raises:

  • UnsupportedBinaryError – If utility_name is not in the supported set (see SUPPORTED_BINARY_UTILITIES).

  • RuntimeError – If a native Windows architecture needed for an architecture-specific utility layout cannot be determined, or an installed Nsight product has incomplete or invalid registry data.

Windows on ARM (WoA) Note:

Binary utilities execute in separate processes and do not need to match the Python process architecture. When choosing among architecture-specific Windows layouts, this API deliberately targets the native machine architecture rather than the Python interpreter architecture. For example, standalone nsys and ncu discovery under x64 Python on an Arm64 machine selects the Arm64 target. This differs from load_nvidia_dynamic_lib and find_static_lib, which target the Python interpreter architecture.

Search order:

  1. NVIDIA Python wheels

    • Scan installed distributions (site-packages) for binary layouts shipped in NVIDIA wheels (e.g., cuda-nvcc).

  2. Conda environments

    • Check Conda-style installation prefixes via CONDA_PREFIX environment variable, which use platform-specific bin directory layouts (Library/bin on Windows, bin on Linux).

  3. Library-specific standalone installations

    • Search the installation paths for the CUDA Toolkit, Nsight Systems, and Nsight Compute.

    3.1. Nsight installations: On Windows, locate Nsight Systems and

    Nsight Compute from their installer registry entries. Select architecture-specific binaries using the native machine architecture, independent of Python. Lookup of the standalone nsys and ncu CLIs is terminal; a miss does not fall through to CUDA Toolkit locations.

    3.2. CUDA Toolkit installation: Use CUDA_PATH or CUDA_HOME

    (in that order), searching bin/x64, bin/x86_64, and bin subdirectories on Windows, or just bin on Linux.

  4. CTK-root canary fallback

    • For utilities that reach this step after the earlier searches miss, resolve the cudart library through the OS dynamic loader, derive the CUDA Toolkit root from it, and search that root’s bin layout.

Note

Results are cached using @functools.cache for performance. The cache persists for the lifetime of the process.

On Windows, executables are identified by their file extensions (.exe, .bat, .cmd). On Unix-like systems, executables are identified by the X_OK (execute) permission bit.

Lookup is restricted to the trusted directories and the canary-derived CTK root listed above.

Example

>>> from cuda.pathfinder import find_nvidia_binary_utility
>>> nvdisasm = find_nvidia_binary_utility("nvdisasm")
>>> if nvdisasm:
...     print(f"Found nvdisasm at: {nvdisasm}")