Skip to content

Clarify CUDA/CuPy install requirements in docs (#8106) #8983

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Shizoqua wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Clarify CUDA/CuPy install requirements in docs (#8106) #8983

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 27 additions & 2 deletions docs/source/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

- [Installation Guide](#installation-guide)
- [Table of Contents](#table-of-contents)
- [GPU-enabled installation (CUDA and CuPy)](#gpu-enabled-installation-cuda-and-cupy)
- [From PyPI](#from-pypi)
- [Milestone release](#milestone-release)
- [Weekly preview release](#weekly-preview-release)
Expand All @@ -30,12 +31,33 @@ Ignite](https://pytorch.org/ignite/), please follow the instructions:

- [Installing the recommended dependencies](#installing-the-recommended-dependencies)

The installation commands below usually end up installing CPU variant of PyTorch. To install GPU-enabled PyTorch:
---

## GPU-enabled installation (CUDA and CuPy)

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.
Comment on lines +38 to +43

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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 -n

Repository: 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:

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.


Installing GPU-enabled PyTorch is enough to run models and transforms on the GPU. Some transforms,
however, additionally use [CuPy](https://cupy.dev/) for GPU-accelerated array operations (for example
when a transform converts a CUDA tensor via `convert_to_cupy`). If CuPy is not installed, these code
paths raise `OptionalImportError: import cupy (No module named 'cupy')`.

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.
Comment on lines +50 to +60

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 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 || true

Repository: 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:

🏁 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 || true

Repository: 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.md

Repository: 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.cfg

Repository: 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.cfg

Repository: 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:

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.


---

Expand Down Expand Up @@ -261,3 +283,6 @@ which correspond to `nibabel`, `scikit-image`,`scipy`, `pillow`, `tensorboard`,
`gdown`, `pytorch-ignite`, `torchvision`, `itk`, `tqdm`, `lmdb`, `psutil`, `cucim`, `openslide-python`, `pandas`, `einops`, `transformers`, `mlflow`, `clearml`, `matplotlib`, `tensorboardX`, `tifffile`, `imagecodecs`, `pyyaml`, `fire`, `jsonschema`, `ninja`, `pynrrd`, `pydicom`, `h5py`, `nni`, `optuna`, `onnx`, `onnxruntime`, `zarr`, `lpips`, `nvidia-ml-py`, `huggingface_hub` and `pyamg` respectively.

- `pip install 'monai[all]'` installs all the optional dependencies.
- The `cucim` extra also provides [CuPy](https://cupy.dev/), which is required by GPU-accelerated
transforms. See [GPU-enabled installation (CUDA and CuPy)](#gpu-enabled-installation-cuda-and-cupy)
for details.