[DOCS] Improve the introduction and installation section of the documentation by gmarkall · Pull Request #293 · NVIDIA/numba-cuda

gmarkall · 2025-06-12T13:08:52Z

The scope of these changes is to make it so that:

A user landing on the index page of the documentation gets a coherent, quick summary of Numba, and links to different parts of the document.
Proceeding through the docs to the first page, they get installation instructions that are both relevant and correct
Following that, the documentation continues with the "usual" introduction to writing CUDA kernels.

The Installation section here is mostly what was called "Overview" before - anything from that section that wasn't to do with installation was pushed into the next page that explains how to write kernels - I have not put much effort into improving that page here.

The Installation section should give users a good reference on how to install numba-cuda and have the required bindings installed and usable, or they should be able to disable the NVIDIA bindings if they don't want to use them.

copy-pr-bot · 2025-06-12T13:08:55Z

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.

gmarkall · 2025-06-12T13:10:39Z

/ok to test

kkraus14 · 2025-06-12T13:12:54Z

docs/source/user/installation.rst

+
+For CUDA 12, ``cuda-nvcc`` and ``cuda-nvrtc`` are required::
+
+    $ conda install -c conda-forge numba-cuda cuda-nvcc cuda-nvrtc "cuda-version>=12.0"


Should we consider just adding these to the conda recipe?

To add, once we depend on cuda-bindings in the conda recipe, cuda-nvrtc is already a dependency. What is cuda-nvcc needed for?

I'm stretching my memory a bit here, but I think it might have been the only way to get libdevice installed (I'm not sure if that's still current).

If it's only for libdevice then that comes from the cuda-nvvm-tools conda package these days that we should depend on instead.

cuda-nvcc was probably used to provide libnvvm. I need to look it up and check which 12.x did we split it from nvcc-impl.

I just remembered - if you want to run the full test suite, you need to have nvcc installed to build the test binaries. I don't know whether this means it makes sense to have it installed for end-users though.

Should we consider just adding these to the conda recipe?

If I run

$ mamba create -n test-install-numba-cuda-015 python=3.12 nvidia::numba-cuda

(using the NVIDIA channel only because 0.15.0 is not yet on conda-forge right now)

then it will install (amongst others)

Package Version Build Channel Size ───────────────────────────────────────────────────────────────────────────────────── Install: ───────────────────────────────────────────────────────────────────────────────────── + cuda-version 12.9 h4f385c5_3 conda-forge 22kB + cuda-nvvm-dev_linux-64 12.9.86 ha770c72_1 conda-forge 27kB + cuda-nvvm-tools 12.9.86 he02047a_1 conda-forge 24MB + cuda-nvvm-impl 12.9.86 he02047a_1 conda-forge 21MB + libnvjitlink 12.9.86 h5888daf_0 conda-forge 31MB + cuda-nvrtc 12.9.86 h5888daf_0 conda-forge 67MB + cuda-nvvm 12.9.86 h69a702a_1 conda-forge 25kB + cuda-bindings 12.9.0 py312h77ce6f0_0 conda-forge Cached + numba 0.61.2 py312h7bcfee6_1 conda-forge Cached + numba-cuda 0.15.0 py_0 nvidia Cached

so it looks like mamba install numba-cuda is going to be sufficient to pull in all required dependencies for running Numba-CUDA - I'll simplify the docs here.

kkraus14 · 2025-06-12T13:15:05Z

docs/source/user/installation.rst

+Setting CUDA Installation Path
+------------------------------
+
+Numba searches for a CUDA toolkit installation in the following order:


I think this order is for the ctypes based bindings and doesn't reflect the cuda-bindings based search order. For cuda-bindings it will follow the behavior described here: https://github.com/NVIDIA/cuda-python/tree/main/cuda_bindings/cuda/bindings/_path_finder#library-loading-search-priority

Thanks - I didn't realise this until our sync meeting today, after I made this PR. Will update.

Might be better to add a note explaining the search order might change in the future?

I'll make it clear that the behaviour using the NVIDIA bindings follows path-finder's logic, and that the ctypes behaviour is for the deprecated path.

docs/source/user/kernels.rst

brandon-b-miller · 2025-06-12T13:24:27Z

docs/source/user/installation.rst

+
+if you are using Conda, or::
+
+   $ pip install cuda-bindings[cu11]


Is cu11 an extra for cuda-bindings? Same with cu12 below

No it is not. We should be doing cuda-bindings[all]==11 / cuda-bindings[all]==12. That being said, I think we should just advertise the numba-cuda[cuXX] path instead?

I would be happy to change this but I'm not clear what the exact correct thing to write should be. Can you make a suggestion please?

I believe we can just keep the text but remove all conda/pip install commands from this section. In the previous section, we already taught users how to install things, and cuda-bindings will be installed there. So, here we just need to teach users how to fall back to ctypes.

Thanks Leo - I've now removed these, and it does read better.

leofang · 2025-06-13T01:49:17Z

@gmarkall the root README also has installation instructions that need to be updated 😅

gmarkall · 2025-06-13T08:20:36Z

@gmarkall the root README also has installation instructions that need to be updated 😅

Thanks for the reminder - I want to handle that in a separate PR when I can get round to it. My thinking here was that a little improvement is better than no improvement because I didn't have time to do both.

These should already be installed by following the recommended install steps.

gmarkall · 2025-06-13T10:36:29Z

Thanks all - I believe I've now addressed all comments (and it does read better as a result!).

gmarkall · 2025-06-13T11:33:01Z

/ok to test

docs/source/user/installation.rst

- NFC: Don't rely on `Dispatcher._compiler` API (NVIDIA#289) - [DOCS] Improve the introduction and installation section of the documentation (NVIDIA#293) - Fix `DeviceNDArray.device_ctypes_pointer` to always be ctypes (NVIDIA#295) - Raise better error when `cuda.bindings` are not available (NVIDIA#294)

- NFC: Don't rely on `Dispatcher._compiler` API (#289) - [DOCS] Improve the introduction and installation section of the documentation (#293) - Fix `DeviceNDArray.device_ctypes_pointer` to always be ctypes (#295) - Raise better error when `cuda.bindings` are not available (#294)

leofang · 2025-06-16T15:41:37Z

@gmarkall the root README also has installation instructions that need to be updated 😅

Thanks for the reminder - I want to handle that in a separate PR when I can get round to it. My thinking here was that a little improvement is better than no improvement because I didn't have time to do both.

Let me take care of this!

gmarkall added 2 commits June 12, 2025 13:47

[DOCS] Rewrite front page and tidy up overview

c10ee51

Make the Overview section focus on Installation

10a7dea

gmarkall requested review from brandon-b-miller and kkraus14 June 12, 2025 13:09

gmarkall added the 3 - Ready for Review Ready for review by team label Jun 12, 2025

gmarkall requested a review from leofang June 12, 2025 13:11

kkraus14 reviewed Jun 12, 2025

View reviewed changes

brandon-b-miller reviewed Jun 12, 2025

View reviewed changes

kkraus14 mentioned this pull request Jun 12, 2025

ENH: update package version to 0.15.0 conda-forge/numba-cuda-feedstock#29

Merged

gmarkall added 4 - Waiting on author Waiting for author to respond to review and removed 3 - Ready for Review Ready for review by team labels Jun 13, 2025

gmarkall added 4 commits June 13, 2025 11:25

Clarify search differences between ctypes and NVIDIA bindings

10dad52

Remove redundant cuda-nvcc and cuda-nvrtc installation from steps

3cabec6

Correct capitalization of NVIDIA

352861f

Remove steps to install NVIDIA bindings

2301177

These should already be installed by following the recommended install steps.

gmarkall added 4 - Waiting on reviewer Waiting for reviewer to respond to author and removed 4 - Waiting on author Waiting for author to respond to review labels Jun 13, 2025

kkraus14 approved these changes Jun 13, 2025

View reviewed changes

docs/source/user/installation.rst Outdated Show resolved Hide resolved

Update docs/source/user/installation.rst

b0b4fbe

kkraus14 merged commit 56c3bae into NVIDIA:main Jun 13, 2025

gmarkall mentioned this pull request Jun 14, 2025

Bump version to 0.15.1 #298

Merged

leofang mentioned this pull request Jun 16, 2025

Update repo readme and point users to the official doc #301

Merged


		For CUDA 12, ``cuda-nvcc`` and ``cuda-nvrtc`` are required::

		$ conda install -c conda-forge numba-cuda cuda-nvcc cuda-nvrtc "cuda-version>=12.0"


		if you are using Conda, or::

		$ pip install cuda-bindings[cu11]

Conversation

gmarkall commented Jun 12, 2025

Uh oh!

copy-pr-bot bot commented Jun 12, 2025

Uh oh!

gmarkall commented Jun 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leofang commented Jun 13, 2025

Uh oh!

gmarkall commented Jun 13, 2025

Uh oh!

gmarkall commented Jun 13, 2025

Uh oh!

gmarkall commented Jun 13, 2025

Uh oh!

Uh oh!

leofang commented Jun 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants