NVIDIA / NVIDIA/cuda-python

[FEA]: Explore pathfinder "scoped search" feature

Open
#1,038 10 comments 0 reactions 1 assignee View on GitHub

@rwgk is already working on this.

Since Sep 26, 2025.

cuda.pathfinder feature P0
Dominant language
Cython
Stars
3.4k
Forks
329
Avg merge
1d 23h
Merged PRs (30d)
116

Description

Problem to solve

The searches implemented in load_nvidia_dynamic_lib() and find_nvidia_header_directory() are completely independent from each other. For example, load_nvidia_dynamic_lib("nvrtc") might resolve to a site-packages path, while load_nvidia_dynamic_lib("nvJitLink") finds a Conda path, and find_nvidia_header_directory("nvvm") locates headers under /usr/local/cuda. This can lead to surprising inconsistencies and confusing behavior deep in the call stack.

Potential approach (with low maintenance as a goal in mind)

Core idea: Introduce the concept of a pivot library that defines the scope for all subsequent searches.

Here, package system means, for example:

  • /usr/local/cuda (or another "standard" CTK installation)
  • Conda (including pixi)
  • site-packages (wheels, PyPI)

How it would work in practice:

  • A client code author decides which library is most pivotal and loads it first.

  • search_scope = cuda.pathfinder.determine_search_scope(pivot_libname="nvrtc") — Loads the pivot library and returns it in a wrapper object.

  • loaded_dl = search_scope.load_nvidia_dynamic_lib("nvJitLink") — Only succeeds if the target library exists in the same package system, otherwise fails with a helpful error.

  • hdr_dir = search_scope.find_nvidia_header_directory("nvvm") — Similarly constrained to the same package system.

This design shifts responsibility for consistency to package managers, which already provide version alignment via pinning. We avoid duplicating those mechanisms and instead ensure our tooling surfaces clear, consistent results.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.