feat(pathfinder): centralize CUDA env var handling, prioritize CUDA_PATH over CUDA_HOME (#1801)

* Squash-merge of PR #1519 (rparolin/env_var_improvements) rebased onto main.

Adds cuda.pathfinder._utils.env_var_constants with canonical search order,
enhances get_cuda_home_or_path() with robust path comparison and caching,
and updates documentation across all packages to reflect the new priority.

Co-authored-by: Rob Parolin <rparolin@nvidia.com>
Made-with: Cursor

* replace _get_cuda_paths() with _get_cuda_path() using pathfinder

Drop os.pathsep splitting of CUDA_PATH/CUDA_HOME in both build_hooks.py files.
Both functions now delegate to get_cuda_home_or_path() from cuda.pathfinder,
returning a single path.

See #1801 (comment)

Made-with: Cursor

* treat empty env vars as undefined in get_cuda_home_or_path()

See #1801 (comment) for the rationale

Made-with: Cursor

* fix(pathfinder): clear get_cuda_home_or_path cache in test fixtures

Made-with: Cursor

* fix(core): update test_build_hooks for _get_cuda_path rename, drop multi-path test

Made-with: Cursor

* refactor(core): use get_cuda_home_or_path() in test conftest skipif

Made-with: Cursor

* refactor(core): use get_cuda_home_or_path() in examples

Made-with: Cursor

* rename get_cuda_home_or_path -> get_cuda_path_or_home

Safe: currently an internal-only API (not yet public).
Made-with: Cursor

* make get_cuda_path_or_home a public API, privatize CUDA_ENV_VARS_ORDERED

Export get_cuda_path_or_home from cuda.pathfinder.__init__. External
consumers now import from cuda.pathfinder directly. Rename constant
to _CUDA_PATH_ENV_VARS_ORDERED and remove all public references to it.

Made-with: Cursor

* docs(pathfinder): manually edit 1.5.0 release notes, fix RST formatting (Cursor)

Made-with: Cursor

* Add 1.5.0, 1.4.3, 1.4.2 in cuda_pathfinder/docs/nv-versions.json

* docs: clarify that CUDA_PATH/CUDA_HOME priority comes from pathfinder

Pathfinder 1.5.0 release notes no longer claim cross-package consistency
(that depends on future bindings/core releases). cuda_bindings env var
docs now defer to pathfinder release notes for migration guidance.

Made-with: Cursor

* fix oversights that slipped in when manually editing cuda_pathfinder/docs/nv-versions.json before

Discovered via independent review from GPT-5.4 Extra High

* fix(pathfinder): change found_via from "CUDA_HOME" to "CUDA_PATH"

Aligns the provenance label with the new CUDA_PATH-first priority.
The label signals the highest-priority env var name, not necessarily
which variable supplied the value.

Discovered via independent review from GPT-5.4 Extra High

Made-with: Cursor

* fix(build): don't import cuda.pathfinder in build_hooks.py

The build backends run in an isolated venv created by pyproject-build.
Although cuda-pathfinder is listed in build-system.requires and gets
installed, the cuda namespace package from backend-path=["."] shadows
the installed cuda-pathfinder, making `from cuda.pathfinder import ...`
fail with ModuleNotFoundError. This broke all CI wheel builds.

Revert _get_cuda_path() to use os.environ.get() directly with
CUDA_PATH > CUDA_HOME priority, and remove cuda-pathfinder from
build-system.requires (it was not there on main; our PR added it).

Made-with: Cursor

* Update pathfinder descriptor catalogs for cusparseLt release 0.9.0

* Slightly enhance comment in _get_cuda_path()

* Add PR #1806 to 1.5.0-notes.rst

* Systematically rename find_in_cuda_home → find_in_cuda_path

* add _cuda_headers_available() guard to conftest files

Add a helper that skips tests when no CUDA path is set, but
asserts that the include/ subdirectory exists when one is — surfacing
stale or incomplete toolkit roots at collection time instead of
letting them fail later in compilation.

Applied in both the root conftest.py and cuda_core/tests/conftest.py.

Made-with: Cursor

---------

Co-authored-by: Rob Parolin <rparolin@nvidia.com>

Author: rwgk

conftest.py

@@ -1,13 +1,31 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+
 import os
 
 import pytest
 
+from cuda.pathfinder import get_cuda_path_or_home
+
+
+# Please keep in sync with the copy in cuda_core/tests/conftest.py.
+def _cuda_headers_available() -> bool:
+    """Return True if CUDA headers are available, False if no CUDA path is set.
+
+    Raises AssertionError if a CUDA path is set but has no include/ subdirectory.
+    """
+    cuda_path = get_cuda_path_or_home()
+    if cuda_path is None:
+        return False
+    assert os.path.isdir(os.path.join(cuda_path, "include")), (
+        f"CUDA path {cuda_path} does not contain an 'include' subdirectory"
+    )
+    return True
+
 
 def pytest_collection_modifyitems(config, items):  # noqa: ARG001
-    cuda_home = os.environ.get("CUDA_HOME")
+    have_headers = _cuda_headers_available()
     for item in items:
         nodeid = item.nodeid.replace("\\", "/")
 
@@ -31,6 +49,10 @@ def pytest_collection_modifyitems(config, items):  # noqa: ARG001
         ):
             item.add_marker(pytest.mark.cython)
 
-            # Gate core cython tests on CUDA_HOME
-            if "core" in item.keywords and not cuda_home:
-                item.add_marker(pytest.mark.skip(reason="CUDA_HOME not set; skipping core cython tests"))
+            # Gate core cython tests on CUDA_PATH
+            if "core" in item.keywords and not have_headers:
+                item.add_marker(
+                    pytest.mark.skip(
+                        reason="Environment variable CUDA_PATH or CUDA_HOME is not set: skipping core cython tests"
+                    )
+                )

cuda_bindings/README.md

@@ -33,7 +33,7 @@ To run these tests:
 
 Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [Installing from Source](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda.bindings`. To build them:
 
-1. Setup environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation.
+1. Setup environment variable `CUDA_PATH` (or `CUDA_HOME`) with the path to the CUDA Toolkit installation. Note: If both are set, `CUDA_PATH` takes precedence.
 2. Run `build_tests` script located in `test/cython` appropriate to your platform. This will both cythonize the tests and build them.
 
 To run these tests:

cuda_bindings/build_hooks.py

@@ -34,13 +34,16 @@
 
 
 @functools.cache
-def _get_cuda_paths() -> list[str]:
-    CUDA_HOME = os.environ.get("CUDA_HOME", os.environ.get("CUDA_PATH", None))
-    if not CUDA_HOME:
-        raise RuntimeError("Environment variable CUDA_HOME or CUDA_PATH is not set")
-    CUDA_HOME = CUDA_HOME.split(os.pathsep)
-    print("CUDA paths:", CUDA_HOME)
-    return CUDA_HOME
+def _get_cuda_path() -> str:
+    # Not using cuda.pathfinder.get_cuda_path_or_home() here because this
+    # build backend runs in an isolated venv where the cuda namespace package
+    # from backend-path shadows the installed cuda-pathfinder. See #1803 for
+    # a workaround to apply after cuda-pathfinder >= 1.5 is released.
+    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    if not cuda_path:
+        raise RuntimeError("Environment variable CUDA_PATH or CUDA_HOME is not set")
+    print("CUDA path:", cuda_path)
+    return cuda_path
 
 
 # -----------------------------------------------------------------------
@@ -133,8 +136,8 @@ def _fetch_header_paths(required_headers, include_path_list):
     if missing_headers:
         error_message = "Couldn't find required headers: "
         error_message += ", ".join(missing_headers)
-        cuda_paths = _get_cuda_paths()
-        raise RuntimeError(f'{error_message}\nIs CUDA_HOME setup correctly? (CUDA_HOME="{cuda_paths}")')
+        cuda_path = _get_cuda_path()
+        raise RuntimeError(f'{error_message}\nIs CUDA_PATH setup correctly? (CUDA_PATH="{cuda_path}")')
 
     return header_dict
 
@@ -291,7 +294,7 @@ def _build_cuda_bindings(strip=False):
 
     global _extensions
 
-    cuda_paths = _get_cuda_paths()
+    cuda_path = _get_cuda_path()
 
     if os.environ.get("PARALLEL_LEVEL") is not None:
         warn(
@@ -307,7 +310,7 @@ def _build_cuda_bindings(strip=False):
     compile_for_coverage = bool(int(os.environ.get("CUDA_PYTHON_COVERAGE", "0")))
 
     # Parse CUDA headers
-    include_path_list = [os.path.join(path, "include") for path in cuda_paths]
+    include_path_list = [os.path.join(cuda_path, "include")]
     header_dict = _fetch_header_paths(_REQUIRED_HEADERS, include_path_list)
     found_types, found_functions, found_values, found_struct, struct_list = _parse_headers(
         header_dict, include_path_list, parser_caching
@@ -347,7 +350,7 @@ def _build_cuda_bindings(strip=False):
     ] + include_path_list
     library_dirs = [sysconfig.get_path("platlib"), os.path.join(os.sys.prefix, "lib")]
     cudalib_subdirs = [r"lib\x64"] if sys.platform == "win32" else ["lib64", "lib"]
-    library_dirs.extend(os.path.join(prefix, subdir) for prefix in cuda_paths for subdir in cudalib_subdirs)
+    library_dirs.extend(os.path.join(cuda_path, subdir) for subdir in cudalib_subdirs)
 
     extra_compile_args = []
     extra_link_args = []

cuda_bindings/docs/source/environment_variables.rst

@@ -15,7 +15,14 @@ Runtime Environment Variables
 Build-Time Environment Variables
 --------------------------------
 
-- ``CUDA_HOME`` or ``CUDA_PATH``: Specifies the location of the CUDA Toolkit.
+- ``CUDA_PATH`` or ``CUDA_HOME``: Specifies the location of the CUDA Toolkit. If both are set, ``CUDA_PATH`` takes precedence.
+
+  .. note::
+     The ``CUDA_PATH`` > ``CUDA_HOME`` priority is determined by ``cuda-pathfinder``.
+     Earlier versions of ``cuda-pathfinder`` (before 1.5.0) used the opposite order
+     (``CUDA_HOME`` > ``CUDA_PATH``). See the
+     `cuda-pathfinder 1.5.0 release notes <https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/release/1.5.0-notes.html>`_
+     for details and migration guidance.
 
 - ``CUDA_PYTHON_PARSER_CACHING`` : bool, toggles the caching of parsed header files during the cuda-bindings build process. If caching is enabled (``CUDA_PYTHON_PARSER_CACHING`` is True), the cache path is set to ./cache_<library_name>, where <library_name> is derived from the cuda toolkit libraries used to build cuda-bindings.
 

cuda_bindings/docs/source/install.rst

@@ -87,11 +87,11 @@ Requirements
 
 [^2]: The CUDA Runtime static library (``libcudart_static.a`` on Linux, ``cudart_static.lib`` on Windows) is part of the CUDA Toolkit. If using conda packages, it is contained in the ``cuda-cudart-static`` package.
 
-Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the ``CUDA_HOME`` (or ``CUDA_PATH``) environment variable to specify the location of your headers. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_HOME`` with:
+Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the ``CUDA_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
 
 .. code-block:: console
 
-   $ export CUDA_HOME=/usr/local/cuda
+   $ export CUDA_PATH=/usr/local/cuda
 
 See `Environment Variables <environment_variables.rst>`_ for a description of other build-time environment variables.
 

cuda_core/README.md

@@ -26,7 +26,7 @@ Alternatively, from the repository root you can use a simple script:
 
 Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [those of cuda.bindings](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda.bindings`. To build them:
 
-1. Set up environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation.
+1. Set up environment variable `CUDA_PATH` (or `CUDA_HOME`) with the path to the CUDA Toolkit installation. Note: If both are set, `CUDA_PATH` takes precedence.
 2. Run `build_tests` script located in `tests/cython` appropriate to your platform. This will both cythonize the tests and build them.
 
 To run these tests:

cuda_core/build_hooks.py

@@ -29,12 +29,15 @@
 
 
 @functools.cache
-def _get_cuda_paths() -> list[str]:
-    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME", None))
+def _get_cuda_path() -> str:
+    # Not using cuda.pathfinder.get_cuda_path_or_home() here because this
+    # build backend runs in an isolated venv where the cuda namespace package
+    # from backend-path shadows the installed cuda-pathfinder. See #1803 for
+    # a workaround to apply after cuda-pathfinder >= 1.5 is released.
+    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
     if not cuda_path:
         raise RuntimeError("Environment variable CUDA_PATH or CUDA_HOME is not set")
-    cuda_path = cuda_path.split(os.pathsep)
-    print("CUDA paths:", cuda_path)
+    print("CUDA path:", cuda_path)
     return cuda_path
 
 
@@ -60,21 +63,20 @@ def _determine_cuda_major_version() -> str:
         return cuda_major
 
     # Derive from the CUDA headers (the authoritative source for what we compile against).
-    cuda_path = _get_cuda_paths()
-    for root in cuda_path:
-        cuda_h = os.path.join(root, "include", "cuda.h")
-        try:
-            with open(cuda_h, encoding="utf-8") as f:
-                for line in f:
-                    m = re.match(r"^#\s*define\s+CUDA_VERSION\s+(\d+)\s*$", line)
-                    if m:
-                        v = int(m.group(1))
-                        # CUDA_VERSION is e.g. 12020 for 12.2.
-                        cuda_major = str(v // 1000)
-                        print("CUDA MAJOR VERSION:", cuda_major)
-                        return cuda_major
-        except OSError:
-            continue
+    cuda_path = _get_cuda_path()
+    cuda_h = os.path.join(cuda_path, "include", "cuda.h")
+    try:
+        with open(cuda_h, encoding="utf-8") as f:
+            for line in f:
+                m = re.match(r"^#\s*define\s+CUDA_VERSION\s+(\d+)\s*$", line)
+                if m:
+                    v = int(m.group(1))
+                    # CUDA_VERSION is e.g. 12020 for 12.2.
+                    cuda_major = str(v // 1000)
+                    print("CUDA MAJOR VERSION:", cuda_major)
+                    return cuda_major
+    except OSError:
+        pass
 
     # CUDA_PATH or CUDA_HOME is required for the build, so we should not reach here
     # in normal circumstances. Raise an error to make the issue clear.
@@ -132,7 +134,7 @@ def get_sources(mod_name):
 
         return sources
 
-    all_include_dirs = [os.path.join(root, "include") for root in _get_cuda_paths()]
+    all_include_dirs = [os.path.join(_get_cuda_path(), "include")]
     extra_compile_args = []
     if COMPILE_FOR_COVERAGE:
         # CYTHON_TRACE_NOGIL indicates to trace nogil functions.  It is not

cuda_core/examples/thread_block_cluster.py

@@ -23,6 +23,7 @@
     ProgramOptions,
     launch,
 )
+from cuda.pathfinder import get_cuda_path_or_home
 
 # print cluster info using a kernel and store results in pinned memory
 code = r"""
@@ -65,9 +66,9 @@ def main():
         print("This example requires NumPy 2.2.5 or later", file=sys.stderr)
         sys.exit(1)
 
-    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    cuda_path = get_cuda_path_or_home()
     if cuda_path is None:
-        print("this example requires a valid CUDA_PATH environment variable set", file=sys.stderr)
+        print("This example requires CUDA_PATH or CUDA_HOME to point to a CUDA toolkit.", file=sys.stderr)
         sys.exit(1)
     cuda_include = os.path.join(cuda_path, "include")
     if not os.path.isdir(cuda_include):

cuda_core/examples/tma_tensor_map.py

@@ -36,6 +36,7 @@
     StridedMemoryView,
     launch,
 )
+from cuda.pathfinder import get_cuda_path_or_home
 
 # ---------------------------------------------------------------------------
 # CUDA kernel that uses TMA to load a 1-D tile into shared memory, then
@@ -103,7 +104,7 @@
 
 
 def _get_cccl_include_paths():
-    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    cuda_path = get_cuda_path_or_home()
     if cuda_path is None:
         print("This example requires CUDA_PATH or CUDA_HOME to point to a CUDA toolkit.", file=sys.stderr)
         sys.exit(1)

cuda_core/pyproject.toml

@@ -6,7 +6,7 @@
 requires = [
     "setuptools>=80",
     "setuptools-scm[simple]>=8",
-    "Cython>=3.2,<3.3"
+    "Cython>=3.2,<3.3",
 ]
 build-backend = "build_hooks"
 backend-path = ["."]