cuda-pathfinder 1.5.0 Release notes#

Released on Mar 24, 2026

Breaking Change#

  • CUDA environment variable priority changed: CUDA_PATH now takes precedence over CUDA_HOME when both are set. Previously, CUDA_HOME had higher priority. If both variables are set and point to different locations, a warning will be issued and CUDA_PATH will be used. This change aligns with industry standards and NVIDIA’s recommended practices.

    The found_via provenance field on LoadedDL, LocatedHeaderDir, LocatedStaticLib, and LocatedBitcodeLib now reports "CUDA_PATH" (previously "CUDA_HOME") when a library or header was discovered through the CUDA_PATH/CUDA_HOME environment variables. The label reflects the highest-priority variable name, not necessarily the variable that supplied the value.

    Migration Guide:

    • If you rely on CUDA_HOME, consider switching to CUDA_PATH

    • If you set both variables, ensure they point to the same CUDA Toolkit installation

    • If they differ intentionally, be aware that CUDA_PATH will now be used

Highlights#

  • Added cuda.pathfinder.get_cuda_path_or_home(), a centralized function for resolving CUDA_PATH/CUDA_HOME. Features:

    • Intelligent path comparison that handles symlinks, case sensitivity, and trailing slashes

    • Result caching for performance (first call determines the path for the process lifetime)

    • Clear warnings when both CUDA_PATH and CUDA_HOME are set but differ

    Future releases of cuda-bindings and cuda-core will adopt this function to ensure consistent CUDA_PATH > CUDA_HOME priority across all cuda-python packages. (PR #1801)