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 thread
coderabbitai[bot] marked this conversation as resolved.

---

Expand Down Expand Up @@ -298,3 +320,6 @@ O(N log N) alternatives to windowed self-attention). Install with
`pip install 'monai[hyena]'`.

- `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.