[FEA] Centralize CUDA environment variable handling and prioritize CUDA_PATH over CUDA_HOME by rparolin · Pull Request #1519 · NVIDIA/cuda-python

rparolin · 2026-01-22T01:13:18Z

This PR introduces centralized CUDA environment variable handling across cuda-python packages with improved consistency and better handling of conflicting environment variable configurations.

The previous implicit priority of CUDA_HOME over CUDA_PATH was inconsistent with:

NVIDIA's own CUDA Toolkit installers (which set CUDA_PATH by default)
CMake's FindCUDAToolkit module (prioritizes CUDA_PATH)

Key Changes

Breaking Change - Environment Variable Priority

Changed the search order priority from CUDA_HOME > CUDA_PATH to CUDA_PATH > CUDA_HOME to align with NVIDIA tooling standards and industry conventions. This affects all packages that query CUDA Toolkit locations (cuda.pathfinder, cuda.core, cuda.bindings).

New Module: `cuda.pathfinder._utils.env_var_constants`

Defines canonical search order CUDA_ENV_VARS_ORDERED = ("CUDA_PATH", "CUDA_HOME")
Zero-dependency module safe for bootstrap scenarios
Single source of truth for environment variable ordering

Enhanced `cuda.pathfinder._utils.env_vars`

Improved get_cuda_home_or_path() with robust path comparison using os.path.samefile()
Handles symlinks, junctions, trailing slashes, and case-insensitivity correctly
Warns users when multiple environment variables are set but point to different locations
Result is cached for process lifetime for consistent behavior
Preserves empty strings when explicitly set

Closes #1433.

copy-pr-bot · 2026-01-22T01:13:22Z

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

rparolin · 2026-01-22T20:08:45Z

/ok to test

copy-pr-bot · 2026-01-22T20:12:05Z

Auto-sync is disabled for ready for review pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

rparolin · 2026-01-22T20:54:57Z

/ok to test

rparolin · 2026-01-22T20:55:56Z

/ok to test

rparolin · 2026-01-22T21:05:10Z

/ok to test

rparolin · 2026-01-22T21:05:27Z

/ok to test

github-actions · 2026-01-22T21:16:39Z

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-1519/
https://nvidia.github.io/cuda-python/pr-preview/pr-1519/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-1519/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-1519/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

rparolin · 2026-01-22T22:46:40Z

/ok to test

rwgk · 2026-01-23T07:16:34Z

cuda_bindings/pyproject.toml

    "setuptools_scm[simple]>=8",
    "cython>=3.2,<3.3",
    "pyclibrary>=0.1.7",
+    "cuda-pathfinder",


It's already on line 34 below. Having it there seemed to work reliably in all situations?

rwgk · 2026-01-27T01:20:06Z

This still uses the old pattern (seems like an easy fix):

cuda-python/cuda_core/build_hooks.py

Lines 27 to 34 in 9209861

    
           @functools.cache 
        
           def _get_cuda_paths() -> list[str]: 
        
               CUDA_PATH = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME", None)) 
        
               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) 
        
               return CUDA_PATH

This

cuda-python/cuda_core/examples/thread_block_cluster.py

Lines 29 to 39 in 9209861

    
           # prepare include 
        
           cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME")) 
        
           if cuda_path is None: 
        
               print("this demo requires a valid CUDA_PATH environment variable set", file=sys.stderr) 
        
               sys.exit(0) 
        
           cuda_include = os.path.join(cuda_path, "include") 
        
           assert os.path.isdir(cuda_include) 
        
           include_path = [cuda_include] 
        
           cccl_include = os.path.join(cuda_include, "cccl") 
        
           if os.path.isdir(cccl_include): 
        
               include_path.insert(0, cccl_include)

should probably be updated to use pathfinder, similar to what I did here a few days ago:

https://github.com/NVIDIA/cuda-python/pull/1517/changes#diff-05f39cca605623dd14a77796b2946b349846c0a2e08e06ea0b485d5819b117a0

I could take care of that in a separate, small PR. Should I?

rwgk · 2026-01-27T01:22:30Z

cuda_bindings/setup.py

+    from cuda.pathfinder._utils.env_vars import get_cuda_home_or_path
+
+    CUDA_HOME = get_cuda_home_or_path()
+except ImportError:


I don't think this fallback code is needed. cuda-bindings depends critically on cuda-pathfinder.

rwgk · 2026-01-27T01:27:41Z

cuda_pathfinder/cuda/pathfinder/_utils/env_vars.py

+        Path to CUDA Toolkit, or None if neither variable is set. Empty strings are
+        preserved and returned as-is if explicitly set in the environment.


Hm, that seems like it could lead to confusing situations. Could we make it so that empty strings are equivalent to to undefined?

Removed preview folders for the following PRs: - PR #1519 - PR #1685

…d 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

…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>

initial commit

8ce5d3a

rparolin added 8 commits January 21, 2026 17:53

restoring multiple path support

44b6050

reverting functionality that was rewritten for no reason

f222d8a

wip

0e35362

wip

5406b6d

wip

41ed40a

wip

195a472

precommit edits

6525f6c

Merge branch 'main' into rparolin/env_var_improvements

a93b851

rparolin marked this pull request as ready for review January 22, 2026 20:12

ci fixes

3ca4b59

wip

2921b31

rparolin added 2 commits January 22, 2026 13:04

wip

b127a47

wip

741f6c6

rparolin closed this Jan 22, 2026

rparolin reopened this Jan 22, 2026

trying to fix ci build-hooks failures

2ce673e

rwgk reviewed Jan 23, 2026

View reviewed changes

rwgk reviewed Jan 27, 2026

View reviewed changes

rparolin assigned rwgk Feb 18, 2026

rparolin added this to the cuda.pathfinder 1.4.0 milestone Feb 18, 2026

rparolin closed this Mar 3, 2026

rwgk removed this from the cuda.pathfinder 1.4.0 milestone Mar 3, 2026

github-actions bot pushed a commit that referenced this pull request Mar 4, 2026

Clean up PR preview folders for 2 closed/merged PRs

d373421

Removed preview folders for the following PRs: - PR #1519 - PR #1685

rwgk mentioned this pull request Mar 20, 2026

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

Merged

		Path to CUDA Toolkit, or None if neither variable is set. Empty strings are
		preserved and returned as-is if explicitly set in the environment.

Conversation

rparolin commented Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes

Breaking Change - Environment Variable Priority

New Module: cuda.pathfinder._utils.env_var_constants

Enhanced cuda.pathfinder._utils.env_vars

Uh oh!

copy-pr-bot bot commented Jan 22, 2026

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

copy-pr-bot bot commented Jan 22, 2026

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

github-actions bot commented Jan 22, 2026

Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

rparolin commented Jan 22, 2026

Uh oh!

rwgk Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

rwgk commented Jan 27, 2026

Uh oh!

rwgk Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

rwgk Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rparolin commented Jan 22, 2026 •

edited

Loading

New Module: `cuda.pathfinder._utils.env_var_constants`

Enhanced `cuda.pathfinder._utils.env_vars`