Installation Guide#

Table of Contents#

MONAI’s core functionality is written in Python 3 (>= 3.10) and only requires Numpy and PyTorch.

The package is currently distributed via Github as the primary source code repository, and the Python package index (PyPI). The pre-built Docker images are made available on DockerHub.

To install optional features such as handling the NIfTI files using Nibabel, or building workflows using PyTorch Ignite, please follow the instructions:

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.

  2. Check the PyTorch Official Guide 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.

  3. Continue to follow the guide and install PyTorch.

  4. 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 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').

MONAI provides a dedicated cupy extra that installs a compatible CuPy build:

pip install 'monai[cupy]'

The cucim extra installs 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-cuda13x for CUDA 13.x) rather than plain cupy. See the CuPy installation guide for the correct package for your CUDA toolkit.

From PyPI#

Milestone release#

To install the current milestone release:

pip install monai

MONAI supports the extras syntax such as pip install 'monai[nibabel]'. The options are

clearml, cucim, cupy, einops, fire, gdown, h5py, huggingface_hub, hyena, ignite, imagecodecs, itk, jsonschema, lmdb, lpips, matplotlib, metrics_reloaded, mlflow, nibabel, nni, nvimgcodec, onnx, openslide, optuna, pandas, pillow, polygraphy, psutil, pyamg, pybind11, pydicom, pynrrd, pynvml, pyyaml, requests, segment_anything, scipy, skimage, tensorboard, tensorboardX, tifffile, torchio, torchvision, tqdm, transformers, zarr

which correspond to the packages: clearml, cucim (cucim-cu12 or cucim-cu13), cupy-cuda13x, einops, fire, gdown, h5py, huggingface_hub, nvsubquadratic, omegaconf, pytorch-ignite, imagecodecs, itk, jsonschema, lmdb, lpips, matplotlib, MetricsReloaded, mlflow, nibabel, nni, filelock, nvidia-nvimgcodec-cu13, onnx, onnxruntime, onnx_graphsurgeon, onnxscript, openslide-python, openslide-bin, optuna, pandas, pillow, polygraphy, psutil, pyamg, pybind11, pydicom, pynrrd, nvidia-ml-py, pyyaml, requests, segment_anything, scipy, scikit-image, tensorboard, tensorboardX, tifffile, torchio, torchvision, tqdm, transformers, zarr.

Almost all of these can be installed together with the all option. For development on MONAI, this should be accompanied by testing which will install the testing static checking packages. Cupy and nvimgcodec are omitted from all since the choice between Cuda 12 and 13 versions of the libraries can’t be resolved when installing and must be manually installed.

The nvimgcodec extra installs GPU-accelerated DICOM decoding for NvImgCodecPydicomReader (pip install 'monai[nvimgcodec]'). It is Linux-only in the extra definition; CUDA 13 is the default. CUDA 12 users should install matching cupy-cuda12x and nvidia-nvimgcodec-cu12 wheels.

The hyena extra pulls in nvsubquadratic, required by HyenaNDUNETR / HyenaMixer / HyenaTransformerBlock (subquadratic O(N log N) alternatives to windowed self-attention). Install with pip install 'monai[hyena]'.

The command pip install 'monai[all,hyena,testing]' installs almost all the optional dependencies.

When installing MONAI, the compiled extensions are not compiled by default. Set the environment variable BUILD_MONAI to 1 when invoking pip to compile these, see below for details.

Weekly preview release#

To install the weekly preview release:

pip install monai-weekly

The weekly build is released to PyPI every Sunday with a pre-release build number dev[%y%U]. To report any issues on the weekly preview, please include the version information:

python -c "import monai; print(monai.__version__)"

Coexistence of package monai and monai-weekly in a system may cause namespace conflicts and ImportError. This is usually a result of running both pip install monai and pip install monai-weekly without uninstalling the existing one first. To address this issue, please uninstall both packages, and retry the installation.

Uninstall the packages#

The packages installed using pip install could be removed by:

pip uninstall -y monai
pip uninstall -y monai-weekly

From conda-forge#

To install the current milestone release:

conda install -c conda-forge monai

From GitHub#

(If you have installed the PyPI release version using pip install monai, please run pip uninstall monai before using the commands from this section. Because pip by default prefers the milestone release.)

The milestone versions are currently planned and released every few months. As the codebase is under active development, you may want to install MONAI from GitHub for the latest features:

Option 1 (as a part of your system-wide module):#

pip install git+https://github.com/Project-MONAI/MONAI

or, to build with MONAI C++/CUDA extensions:

BUILD_MONAI=1 pip install git+https://github.com/Project-MONAI/MONAI

On Windows the inline BUILD_MONAI=1 pip install ... form is not supported by cmd.exe or PowerShell. Set the environment variable first, then run either install command shown above:

:: cmd.exe
set BUILD_MONAI=1
pip install git+https://github.com/Project-MONAI/MONAI

# PowerShell
$env:BUILD_MONAI="1"
pip install git+https://github.com/Project-MONAI/MONAI

To build the extensions, if the system environment already has a version of PyTorch installed, --no-build-isolation might be preferred:

BUILD_MONAI=1 pip install --no-build-isolation git+https://github.com/Project-MONAI/MONAI

When using build isolation (pip’s default behaviour), a version of PyTorch must be installed which may not be the same as an existing install. This can cause the compiled libraries to be built against an ABI-incompatible PyTorch and thus not function at runtime. Building without isolation requires the current environment to have the necessary building libraries already installed. See the build-system section of pyproject.toml for these libraries, or use the following to install them in a bash environment:

python monai/config/print_dependencies.py build-system | xargs -d '\n' pip install --no-build-isolation

An alternative solution is to use built constraints during installation:

pip freeze | grep torch > constraints.txt
pip install --build-constraint constraints.txt git+https://github.com/Project-MONAI/MONAI

this command will download and install the current dev branch of MONAI from GitHub.

This documentation website by default shows the information for the latest version.

Option 2 (editable installation):#

To install an editable version of MONAI, it is recommended to clone the codebase directly:

git clone https://github.com/Project-MONAI/MONAI.git

This command will create a MONAI/ folder in your current directory. You can install it by running:

cd MONAI/
pip install -e .
# or pip install -e '.[all,testing]' to include most of the dependencies

or, to build with MONAI C++/CUDA extensions and install:

cd MONAI/
BUILD_MONAI=1 pip install -e .
# for MacOS
BUILD_MONAI=1 CC=clang CXX=clang++ pip install -e .

On Windows set the environment variable before running pip install -e .:

:: cmd.exe
cd MONAI/
set BUILD_MONAI=1
pip install -e .

# PowerShell
cd MONAI/
$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-isolation flag to force the use of that version, or use the --build-constraint method.

To uninstall the package please run:

cd MONAI/
pip uninstall -y monai

# to further clean up the MONAI/ folder (Bash script)
./runtests.sh --clean

Alternatively, simply adding the root directory of the cloned source code (e.g., /workspace/Documents/MONAI) to your $PYTHONPATH and the codebase is ready to use (without the additional features of MONAI C++/CUDA extensions).

The C++/CUDA extension features are currently experimental, a pre-compiled version is made available via the recent docker image releases. Building the extensions from source may require Ninja and CUDA Toolkit. By default, CUDA extension is built if torch.cuda.is_available(). It’s possible to force building by setting FORCE_CUDA=1 environment variable.

Validating the install#

You can verify the installation by:

python -c "import monai; monai.config.print_config()"

If the installation is successful, this command will print out the MONAI version information, and this confirms the core modules of MONAI are ready-to-use.

MONAI version string#

The MONAI version string shows the current status of your local installation. For example:

MONAI version: 0.1.0+144.g52c763d.dirty

  • 0.1.0 indicates that your installation is based on the 0.1.0 milestone release.

  • +144 indicates that your installation is 144 git commits ahead of the milestone release.

  • g52c763d indicates that your installation corresponds to the git commit hash 52c763d.

  • dirty indicates that you have modified the codebase locally, and the codebase is inconsistent with 52c763d.

From DockerHub#

Make sure you have installed the NVIDIA driver and Docker 19.03+ for your Linux distribution. Note that you do not need to install the CUDA toolkit on the host, but the driver needs to be installed. Please find out more information on nvidia-docker.

Assuming that you have the Nvidia driver and Docker 19.03+ installed, running the following command will download and start a container with the latest version of MONAI. The latest dev branch of MONAI from GitHub is included in the image.

docker run --gpus all --rm -ti --ipc=host projectmonai/monai:latest

You can also run a milestone release docker image by specifying the image tag, for example:

docker run --gpus all --rm -ti --ipc=host projectmonai/monai:0.1.0