Clarify CUDA/CuPy install requirements in docs (#8106)#8983
Conversation
Signed-off-by: Shizoqua <hr.lanreshittu@yahoo.com>
📝 WalkthroughWalkthroughDocs-only change to docs/source/installation.md. Adds a Table of Contents entry for GPU-enabled installation, expands that section with CuPy-specific guidance (behavior when CuPy is missing, installing via the cucim extra, CUDA-version-specific package naming with a link to CuPy install docs), and adds a bullet in the recommended dependencies section pointing to the GPU-enabled installation section. Estimated code review effort: 1 (Trivial) | ~5 minutes Changes
Sequence Diagram(s)Not applicable — documentation-only change. Related issues: Suggested labels: documentation Suggested reviewers: none specified Poem: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/source/installation.md`:
- Around line 38-43: Reword the PyTorch/CUDA installation guidance in the
installation section to align with the pip flow: the current text in the PyTorch
install step suggests manually downloading CUDA and setting CUDA_PATH, which is
misleading for prebuilt pip wheels. Update the instructions around the
PyTorch/CUDA step to direct users to the PyTorch CUDA selector or wheel index,
and make clear that the pip wheels already bundle the CUDA runtime; keep the
surrounding MONAI install guidance in the same place.
- Around line 50-60: Clarify the CuPy dependency chain in the installation docs:
the `cucim` extra does not install CuPy directly, it installs
`cucim-cu12`/`cucim-cu13`, which then brings in the matching
`cupy-cuda12x`/`cupy-cuda13x` wheel. Update the wording in the `pip install
'monai[cucim]'` section and the later CuPy note so both references explicitly
describe this transitive dependency, using the existing installation docs text
as the location guide.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 383d0ea4-20af-433b-9cbe-21f50f3e9ba4
📒 Files selected for processing (1)
docs/source/installation.md
| The installation commands below usually end up installing the CPU variant of PyTorch. To install GPU-enabled PyTorch: | ||
|
|
||
| 1. Install the latest NVIDIA driver. | ||
| 1. Check [PyTorch Official Guide](https://pytorch.org/get-started/locally/) for the recommended CUDA versions. For Pip package, the user needs to download the CUDA manually, install it on the system, and ensure CUDA_PATH is set properly. | ||
| 1. Continue to follow the guide and install PyTorch. | ||
| 1. Install MONAI using one the ways described below. | ||
| 1. Install MONAI using one of the ways described below. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map the file and inspect the relevant sections with line numbers.
wc -l docs/source/installation.md
sed -n '1,120p' docs/source/installation.md | cat -n
printf '\n---\n'
sed -n '260,320p' docs/source/installation.md | cat -nRepository: Project-MONAI/MONAI
Length of output: 7481
🌐 Web query:
PyTorch official installation guide pip CUDA_PATH manual download CUDA wheel selector locally install
💡 Result:
To install PyTorch with CUDA support, the official and recommended method is to use the interactive installer on the PyTorch website, which generates the correct pip or Conda command based on your operating system, Python version, and CUDA version [1][2][3]. For scenarios where you need to manually manage or download specific CUDA-enabled wheels, follow these steps: Official Installation Guide The primary resource for installation is the PyTorch Get Started page (https://pytorch.org/get-started/locally/) [1][3]. The page provides an interactive selector that detects your system preferences and provides the precise installation command [1][4]. Manual Wheel Selection and Local Install If you need to install a specific wheel file (e.g., for offline installation or custom environments), you can access the PyTorch binary repository directly [5][6]: 1. Repository Access: All PyTorch wheels are hosted at https://download.pytorch.org/whl/ [6]. 2. Selecting CUDA Versions: Within this repository, directories are organized by CUDA version (e.g., /cu126/ for CUDA 12.6) [5][6]. 3. Finding the Wheel: Navigate to the sub-directory matching your desired CUDA version and the torch package [5]. You can identify the correct file based on your Python version (e.g., cp312 for Python 3.12) and your system architecture (e.g., linux_x86_64, win_amd64) [7]. 4. Installing Locally: Once you have the direct URL to the.whl file, you can install it using pip: pip install <URL_TO_WHEEL_FILE> [8] Alternative: Index-URL Installation If you have a local environment where you want to force pip to use the official PyTorch binary repository for dependencies, you can specify the index-url: pip install torch==+cu --index-url https://download.pytorch.org/whl/cu [8] Environment Variables While CUDA_PATH is a standard system environment variable used by NVIDIA drivers, PyTorch binaries downloaded from the official repository generally include their own CUDA runtime libraries, meaning you do not typically need to configure CUDA_PATH for the pre-compiled pip packages to function, provided your system has a compatible NVIDIA driver installed [9][4]. If you are building PyTorch from source, you may need to ensure your PATH and CMAKE_PREFIX_PATH are configured correctly to point to your local CUDA installation [9][10].
Citations:
- 1: https://pytorch.org/get-started/locally/
- 2: https://pytorch.org/
- 3: Doc is unclear on how to install pytorch with Cuda via pip pytorch/pytorch#107580
- 4: https://github.com/pytorch/pytorch.github.io/blob/master/get_started/installation/windows.md
- 5: https://download.pytorch.org/whl/cu126/torch/
- 6: https://download.pytorch.org/whl/
- 7: https://download.pytorch.org/whl/torch
- 8: https://discuss.pytorch.org/t/install-particular-pytorch-nightly/186853
- 9: https://github.com/pytorch/pytorch?S_TACT=333AC01A
- 10: https://pypi.org/project/torch/2.10.0/
Reword the PyTorch/CUDA install step. docs/source/installation.md:38-42
The pip flow should point users to PyTorch’s CUDA selector or wheel index; prebuilt pip wheels already include the CUDA runtime, so “download CUDA manually” and CUDA_PATH are misleading here.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/installation.md` around lines 38 - 43, Reword the PyTorch/CUDA
installation guidance in the installation section to align with the pip flow:
the current text in the PyTorch install step suggests manually downloading CUDA
and setting CUDA_PATH, which is misleading for prebuilt pip wheels. Update the
instructions around the PyTorch/CUDA step to direct users to the PyTorch CUDA
selector or wheel index, and make clear that the pip wheels already bundle the
CUDA runtime; keep the surrounding MONAI install guidance in the same place.
| CuPy is provided through the `cucim` extra, so installing MONAI with that extra pulls in a compatible | ||
| CuPy build: | ||
|
|
||
| ```bash | ||
| pip install 'monai[cucim]' | ||
| ``` | ||
|
|
||
| If you prefer to install CuPy directly, note that the PyPI package name is CUDA-version specific | ||
| (e.g. `cupy-cuda12x` for CUDA 12.x, `cupy-cuda11x` for CUDA 11.x) rather than plain `cupy`. See the | ||
| [CuPy installation guide](https://docs.cupy.dev/en/stable/install.html) for the correct package for | ||
| your CUDA toolkit. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## docs/source/installation.md (around lines 40-80)\n'
nl -ba docs/source/installation.md | sed -n '40,80p'
printf '\n## search for cucim/cupy mentions in repo\n'
rg -n --hidden -S "cucim|cupy" docs pyproject.toml setup.py setup.cfg src .github 2>/dev/null || trueRepository: Project-MONAI/MONAI
Length of output: 250
🌐 Web query:
CuPy installation guide current stable CUDA-specific wheel names cupy-cuda11x cupy-cuda12x cupy-cuda13x plain cupy
💡 Result:
To install CuPy on a system with a CUDA-enabled NVIDIA GPU, you should use the precompiled binary wheel packages that correspond to your installed CUDA Toolkit version [1][2]. These packages are named according to the CUDA version they support [1][3]. Current stable CuPy CUDA-specific wheel packages include: - cupy-cuda13x: For systems using NVIDIA CUDA Toolkit 13.x [1][4]. - cupy-cuda12x: For systems using NVIDIA CUDA Toolkit 12.x [1][2]. - cupy-cuda11x: This package remains available for systems using older CUDA Toolkit versions (e.g., v11.x), though it is no longer the primary focus for new releases [5][6]. Installation Instructions To install the package, use pip with the corresponding wheel name [1][3]: pip install cupy-cuda13x pip install cupy-cuda12x pip install cupy-cuda11x Optional CUDA Component Wheels By default, these commands install only the core CuPy library, assuming a compatible CUDA Toolkit is already installed on your system [1][3]. If you prefer not to install a system-wide CUDA Toolkit, you can install CuPy along with the necessary NVIDIA CUDA component wheels by adding the [ctk] tag [1][2]: pip install "cupy-cuda13x[ctk]" Important Considerations - Conflict Prevention: Ensure you only have one CuPy package installed at a time [1][5]. The cupy package (used for source installations) conflicts with the CUDA-specific wheel packages (cupy-cudaXX) [1][2]. You can verify your current installation with: pip freeze | grep cupy - Plain cupy Package: The plain cupy package on PyPI is typically intended for source installations [1][3]. For most users, using the precompiled cupy-cudaXX wheels is strongly recommended [1][7]. - Pre-releases: If you need to install a pre-release version, use the following command structure: pip install cupy-cuda13x --pre -U -f https://pip.cupy.dev/pre
Citations:
- 1: https://docs.cupy.dev/en/stable/install.html
- 2: https://github.com/cupy/cupy/blob/main/docs/source/install.rst
- 3: https://docs.cupy.dev/en/v14.0.0/install.html
- 4: https://pypi.org/project/cupy-cuda13x/
- 5: https://docs.cupy.dev/en/v13.5.1/install.html
- 6: https://docs.cupy.dev/en/v13.5.0/install.html
- 7: https://pypi.org/project/cupy/
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## docs/source/installation.md (lines 45-70)\n'
awk 'NR>=45 && NR<=70 { printf "%4d %s\n", NR, $0 }' docs/source/installation.md
printf '\n## repo mentions of cucim extra definition\n'
rg -n -S "\[cucim\]|cucim" pyproject.toml setup.py setup.cfg requirements* . 2>/dev/null || trueRepository: Project-MONAI/MONAI
Length of output: 30179
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## docs/source/installation.md (lines 270-292)\n'
awk 'NR>=270 && NR<=292 { printf "%4d %s\n", NR, $0 }' docs/source/installation.mdRepository: Project-MONAI/MONAI
Length of output: 1662
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## setup.cfg (lines 115-130)\n'
awk 'NR>=115 && NR<=130 { printf "%4d %s\n", NR, $0 }' setup.cfgRepository: Project-MONAI/MONAI
Length of output: 718
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n## setup.cfg (lines 118-126)\n'
awk 'NR>=118 && NR<=126 { printf "%4d %s\n", NR, $0 }' setup.cfgRepository: Project-MONAI/MONAI
Length of output: 473
🌐 Web query:
PyPI cucim-cu12 depends on cupy CUDA-specific wheel or installs CuPy dependency
💡 Result:
Yes, the PyPI package cucim-cu12 explicitly declares a dependency on the CUDA-specific CuPy wheel, cupy-cuda12x [1][2][3]. When you install cucim-cu12 via pip, it will automatically pull in the corresponding cupy-cuda12x package as a required dependency to ensure proper CUDA 12 support for the cuCIM toolkit [1][2]. The project's dependency configuration specifically uses the cupy-cuda12x wheel to match the CUDA version indicated by the package name (cu12) [2].
Citations:
- 1: https://pypi.org/project/cucim-cu12/26.2.0/
- 2: https://github.com/rapidsai/cucim/blob/main/dependencies.yaml
- 3: https://pypistats.org/packages/cucim-cu12
Clarify the CuPy dependency chain
monai[cucim] installs cucim-cu12/cucim-cu13, which then pull in the matching cupy-cuda12x/cupy-cuda13x wheel. Say that explicitly instead of implying the extra installs CuPy directly. Also update the later note at lines 286-288.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/source/installation.md` around lines 50 - 60, Clarify the CuPy
dependency chain in the installation docs: the `cucim` extra does not install
CuPy directly, it installs `cucim-cu12`/`cucim-cu13`, which then brings in the
matching `cupy-cuda12x`/`cupy-cuda13x` wheel. Update the wording in the `pip
install 'monai[cucim]'` section and the later CuPy note so both references
explicitly describe this transitive dependency, using the existing installation
docs text as the location guide.
1 participant
Fixes #8106
Description
The installation docs did not make it clear that some MONAI transforms require CuPy for GPU-accelerated array operations. Users who ran GPU inference hit
OptionalImportError: import cupy (No module named 'cupy')with no obvious guidance —pip install cupyfails because the real package is CUDA-version specific (cupy-cuda12x), and it was not documented that thecucimextra provides CuPy.This PR updates
docs/source/installation.mdto:## GPU-enabled installation (CUDA and CuPy)section (with a Table of Contents entry) instead of an unlabeled paragraph.convert_to_cupy), what error appears when it is missing, and that CuPy is installed through thecucimextra (pip install 'monai[cucim]').cupy-cuda12x/cupy-cuda11x), linking to the CuPy installation guide.Docs-only change; no code or public API is modified.
Types of changes
./runtests.sh -f -u --net --coverage../runtests.sh --quick --unittests --disttests.make htmlcommand in thedocs/folder.