Switch to cuda-toolkit metapackage for wheel dependencies with streamlined documentation (#883)

* Initial plan

* Switch to cuda-toolkit metapackage for wheel dependencies

Co-authored-by: leofang <[email protected]>

* Merge cuda-toolkit extras into single lines

- cuda_bindings: merge nvcc,nvrtc,nvjitlink,nvvm into single line
- cuda_pathfinder: merge all extras except cufile (platform conditional) for cu12/cu13

Co-authored-by: leofang <[email protected]>

* Add test-cu13 dependency now that cupy-cuda13x is available

Co-authored-by: leofang <[email protected]>

* Add release notes and update installation guides for cuda-toolkit dependency change

- Add release notes for all modules (cuda-bindings 13.0.2, cuda-core 0.3.3, cuda-python 13.0.2)
- Update installation guides to explain cuda-toolkit metapackage benefits
- Clarify improved dependency resolution and version constraints
- Document backward compatibility (user-facing commands unchanged)

Co-authored-by: leofang <[email protected]>

* Address reviewer feedback: move release notes to X.Y format and remove conda references

Co-authored-by: leofang <[email protected]>

* Address reviewer feedback: simplify documentation and remove overselling language

Co-authored-by: leofang <[email protected]>

* Remove NVCC from dependencies and fix conda documentation

- Remove nvcc from cuda-toolkit dependencies as it was only needed for libNVVM access
- NVVM now has its own wheel in CUDA 13, so NVCC compiler is no longer needed
- Update documentation to remove nvcc from optional dependencies list
- Fix typo in conda documentation and add example usage
- Add release notes explaining NVCC removal as breaking change
- Users who need NVCC should explicitly install nvidia-cuda-nvcc-cu13

Co-authored-by: leofang <[email protected]>

* Fix CUDA 13 wheel names, clean up release notes, and restore nvcc in pathfinder

Co-authored-by: leofang <[email protected]>

* Apply suggestions from code review

* Fix conda version pinning, markdown backticks, and improve release notes grammar

Co-authored-by: leofang <[email protected]>

* Add two missing "the"

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: leofang <[email protected]>
Co-authored-by: Leo Fang <[email protected]>
Co-authored-by: Ralf W. Grosse-Kunstleve <[email protected]>

Author: 3 people

cuda_bindings/docs/source/install.md

@@ -10,7 +10,7 @@
 * Optionally, NVRTC, nvJitLink, NVVM, and cuFile from CUDA Toolkit 13.x
 
 ```{note}
-The optional CUDA Toolkit components can be installed via PyPI, Conda, OS-specific package managers, or local installers (as described in the CUDA Toolkit [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html) and [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) Installation Guides).
+The optional CUDA Toolkit components are now installed via the `cuda-toolkit` metapackage from PyPI for improved dependency resolution. Components can also be installed via Conda, OS-specific package managers, or local installers (as described in the CUDA Toolkit [Windows](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html) and [Linux](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html) Installation Guides).
 ```
 
 Starting from v12.8.0, `cuda-python` becomes a meta package which currently depends only on `cuda-bindings`; in the future more sub-packages will be added to `cuda-python`. In the instructions below, we still use `cuda-python` as example to serve existing users, but everything is applicable to `cuda-bindings` as well.
@@ -27,12 +27,14 @@ Install all optional dependencies with:
 pip install -U cuda-python[all]
 ```
 
-Where the optional dependencies are:
+Where the optional dependencies include:
 
-* nvidia-cuda-nvrtc (Provides NVRTC shared library)
-* nvidia-nvjitlink (Provides nvJitLink shared library)
-* nvidia-cuda-nvcc (Provides NVVM shared library)
-* nvidia-cufile (Provides cuFile shared library)
+* `nvidia-cuda-nvrtc` (NVRTC runtime compilation library)  
+* `nvidia-nvjitlink` (nvJitLink library)
+* `nvidia-nvvm` (NVVM library)
+* `nvidia-cufile` (cuFile library, Linux only)
+
+These are now installed through the `cuda-toolkit` metapackage for improved dependency resolution.
 
 
 ## Installing from Conda
@@ -41,6 +43,15 @@ Where the optional dependencies are:
 $ conda install -c conda-forge cuda-python
 ```
 
+```{note}
+When using conda, the `cuda-version` metapackage can be used to control the versions of CUDA Toolkit components that are installed to the conda environment.
+```
+
+For example:
+```console
+$ conda install -c conda-forge cuda-python cuda-version=13
+```
+
 
 ## Installing from Source
 

cuda_bindings/docs/source/release/13.X.Y-notes.rst

@@ -12,10 +12,12 @@ Released on TBD
 Highlights
 ----------
 
+* Migrated wheel dependencies from individual NVIDIA packages to the ``cuda-toolkit`` metapackage for improved dependency resolution and version constraints.
 * Automatic CUDA library path detection based on ``CUDA_HOME``, eliminating the need to manually set ``LIBRARY_PATH`` environment variables for installation.
+* The ``[all]`` optional dependencies now use ``cuda-toolkit`` with appropriate extras instead of individual packages. The NVCC compiler is no longer automatically installed with ``pip install cuda-python[all]`` as it was previously included only to access the NVVM library, which now has its own dedicated wheel. Users who need the NVCC compiler should explicitly install it with ``pip install cuda-toolkit[nvcc]==X.Y`` with the appropriate version for their needs.
 
 
 Known issues
 ------------
 
-* Updating from older versions (v12.6.2.post1 and below) via ``pip install -U cuda-python`` might not work. Please do a clean re-installation by uninstalling ``pip uninstall -y cuda-python`` followed by installing ``pip install cuda-python``.
+* Updating from older versions (v12.6.2.post1 and below) via ``pip install -U cuda-python`` might not work. Please do a clean re-installation by uninstalling ``pip uninstall -y cuda-python`` followed by installing ``pip install cuda-python``.

cuda_bindings/pyproject.toml

@@ -33,11 +33,8 @@ dependencies = [
 
 [project.optional-dependencies]
 all = [
-    "nvidia-cuda-nvcc~=13.0",
-    "nvidia-cuda-nvrtc~=13.0",
-    "nvidia-nvjitlink~=13.0",
-    "nvidia-nvvm~=13.0",
-    "nvidia-cufile; sys_platform == 'linux'",
+    "cuda-toolkit[nvrtc,nvjitlink,nvvm]==13.*",
+    "cuda-toolkit[cufile]==13.*; sys_platform == 'linux'",
 ]
 
 test = [

cuda_core/docs/source/install.md

@@ -17,11 +17,11 @@ dependencies are as follows:
 
 ## Installing from PyPI
 
-`cuda.core` works with `cuda.bindings` (part of `cuda-python`) 11 or 12. For example with CUDA 12:
+`cuda.core` works with `cuda.bindings` (part of `cuda-python`) 11 or 12. Test dependencies now use the ``cuda-toolkit`` metapackage for improved dependency resolution. For example with CUDA 12:
 ```console
 $ pip install cuda-core[cu12]
 ```
-and likewise use `[cu11]` for CUDA 11.
+and likewise use `[cu11]` for CUDA 11, or `[cu13]` for CUDA 13.
 
 Note that using `cuda.core` with NVRTC installed from PyPI via `pip install` requires
 `cuda.bindings` 12.8.0+ or 11.8.6+. Likewise, with nvJitLink it requires 12.8.0+.

cuda_core/docs/source/release/0.X.Y-notes.rst

@@ -25,6 +25,7 @@ New features
 ------------
 
 - Added :attr:`Device.arch` property that returns the compute capability as a string (e.g., '75' for CC 7.5), providing a convenient alternative to manually concatenating the compute capability tuple.
+- CUDA 13.x testing support through new ``test-cu13`` dependency group.
 
 
 New examples

cuda_core/pyproject.toml

@@ -50,9 +50,9 @@ cu11 = ["cuda-bindings[all]==11.8.*"]
 cu12 = ["cuda-bindings[all]==12.*"]
 cu13 = ["cuda-bindings[all]==13.*"]
 test = ["cython>=3.0", "setuptools", "pytest>=6.2.4"]
-test-cu11 = ["cuda-core[test]", "cupy-cuda11x", "nvidia-cuda-runtime-cu11"]  # runtime headers needed by CuPy
-test-cu12 = ["cuda-core[test]", "cupy-cuda12x", "nvidia-cuda-runtime-cu12"]  # runtime headers needed by CuPy
-# TODO add test-cu13 once CuPy is ready
+test-cu11 = ["cuda-core[test]", "cupy-cuda11x", "cuda-toolkit[cudart]==11.*"]  # runtime headers needed by CuPy
+test-cu12 = ["cuda-core[test]", "cupy-cuda12x", "cuda-toolkit[cudart]==12.*"]  # runtime headers needed by CuPy
+test-cu13 = ["cuda-core[test]", "cupy-cuda13x", "cuda-toolkit[cudart]==13.*"]  # runtime headers needed by CuPy
 
 [project.urls]
 homepage = "https://nvidia.github.io/cuda-python/"

cuda_pathfinder/pyproject.toml

@@ -15,35 +15,12 @@ test = [
     "pytest>=6.2.4",
 ]
 nvidia_wheels_cu12 = [
-    "nvidia-cublas-cu12",
-    "nvidia-cuda-nvcc-cu12",
-    "nvidia-cuda-nvrtc-cu12",
-    "nvidia-cuda-runtime-cu12",
-    "nvidia-cufft-cu12",
-    "nvidia-cufile-cu12; sys_platform != 'win32'",
-    "nvidia-curand-cu12",
-    "nvidia-cusolver-cu12",
-    "nvidia-cusparse-cu12",
-    "nvidia-npp-cu12",
-    "nvidia-nvfatbin-cu12",
-    "nvidia-nvjitlink-cu12",
-    "nvidia-nvjpeg-cu12",
+    "cuda-toolkit[nvcc,cublas,nvrtc,cudart,cufft,curand,cusolver,cusparse,npp,nvfatbin,nvjitlink,nvjpeg]==12.*",
+    "cuda-toolkit[cufile]==12.*; sys_platform != 'win32'",
 ]
 nvidia_wheels_cu13 = [
-    "nvidia-cublas",
-    "nvidia-cuda-nvcc",
-    "nvidia-cuda-nvrtc",
-    "nvidia-cuda-runtime",
-    "nvidia-cufft",
-    "nvidia-cufile; sys_platform != 'win32'",
-    "nvidia-curand",
-    "nvidia-cusolver",
-    "nvidia-cusparse",
-    "nvidia-npp",
-    "nvidia-nvfatbin",
-    "nvidia-nvjitlink",
-    "nvidia-nvjpeg",
-    "nvidia-nvvm",
+    "cuda-toolkit[nvcc,cublas,nvrtc,cudart,cufft,curand,cusolver,cusparse,npp,nvfatbin,nvjitlink,nvjpeg,nvvm]==13.*",
+    "cuda-toolkit[cufile]==13.*; sys_platform != 'win32'",
 ]
 
 [project.urls]