From 395d085c8af4bbd6c783f46e5bbb71df35cd42dd Mon Sep 17 00:00:00 2001 From: Lanre Shittu <136805224+Shizoqua@users.noreply.github.com> Date: Sun, 16 Aug 2026 19:16:02 +0100 Subject: [PATCH 1/2] Clarify CUDA/CuPy install requirements in docs (#8106) Signed-off-by: Lanre Shittu <136805224+Shizoqua@users.noreply.github.com> --- docs/source/installation.md | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/source/installation.md b/docs/source/installation.md index 006ac23cda..641f41de18 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -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) @@ -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. + +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. --- From 503290fa13f3bc42b8881f8899ea979370d1f84b Mon Sep 17 00:00:00 2001 From: Lanre Shittu <136805224+Shizoqua@users.noreply.github.com> Date: Sun, 30 Aug 2026 17:39:39 +0100 Subject: [PATCH 2/2] docs(installation): correct CuPy/cucim extras guidance - Update GPU/CUDA step to note that PyTorch wheels bundle the CUDA runtime and do not require manual CUDA download or CUDA_PATH. - Replace the statement that CuPy is installed via the cucim extra; CuPy is now installed via the dedicated monai[cupy] extra. The cucim extra only installs cuCIM. - Update CuPy example versions to cupy-cuda13x for CUDA 13.x. - Quote .[all,testing] in editable-install example. - Fix --no-build-isoloation typo. Signed-off-by: Lanre Shittu <136805224+Shizoqua@users.noreply.github.com> --- docs/source/installation.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/source/installation.md b/docs/source/installation.md index 641f41de18..0ce37ffbc6 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -38,7 +38,7 @@ Ignite](https://pytorch.org/ignite/), please follow the instructions: 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. Check the [PyTorch Official Guide](https://pytorch.org/get-started/locally/) for the recommended CUDA versions. For Pip packages, PyTorch wheels already bundle the CUDA runtime, so you only need to pick the CUDA version matching your driver from the selector and install with the provided command. You do not need to manually download CUDA or set `CUDA_PATH`. 1. Continue to follow the guide and install PyTorch. 1. Install MONAI using one of the ways described below. @@ -47,15 +47,18 @@ however, additionally use [CuPy](https://cupy.dev/) for GPU-accelerated array op 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: +MONAI provides a dedicated `cupy` extra that installs a compatible CuPy build: ```bash -pip install 'monai[cucim]' +pip install 'monai[cupy]' ``` +The `cucim` extra installs [cuCIM](https://github.com/rapidsai/cucim) (`cucim-cu12` or `cucim-cu13` +depending on your Python version), which is a separate GPU image-processing library and does not +install CuPy. + 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 +(e.g. `cupy-cuda12x` for CUDA 12.x, `cupy-cuda13x` for CUDA 13.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. @@ -206,7 +209,7 @@ You can install it by running: ```bash cd MONAI/ pip install -e . -# or pip install -e .[all,testing] to include most of the dependencies +# or pip install -e '.[all,testing]' to include most of the dependencies ``` or, to build with MONAI C++/CUDA extensions and install: @@ -234,7 +237,7 @@ $env:BUILD_MONAI="1" pip install -e . ``` -If the compiled extensions were built by pip against a different version of PyTorch than the one in your environment, you may need to run the above with the `--no-build-isoloation` flag to force the use of that version, or use the `--build-constraint` method. +If the compiled extensions were built by pip against a different version of PyTorch than the one in your environment, you may need to run the above with the `--no-build-isolation` flag to force the use of that version, or use the `--build-constraint` method. To uninstall the package please run: