Install MONAI 1.5.2: Medical Imaging AI Framework Guide

By the end of this walkthrough you’ll have MONAI 1.5.2 running on your machine, verified against a config print-out, with the right extras installed so NIfTI and DICOM files actually load. Total time: about 10-15 minutes if you already have Python and a GPU driver, longer if you’re going the Docker route from scratch.

MONAI is the PyTorch-based medical imaging AI framework built by NVIDIA, the NIH, and King’s College London under the Apache License. If you’re doing segmentation, classification, or registration on CT/MRI/pathology data, this is what you install instead of writing your own DICOM pipeline. The MONAI paper on arXiv covers the design rationale if you want to understand why certain architectural choices were made.

System requirements for MONAI 1.5.2

MONAI itself is lightweight. What’s heavy is PyTorch and CUDA sitting underneath it. Per the GitHub README, MONAI depends directly on NumPy and PyTorch, with many optional dependencies. PyTorch support covers the current version plus three previous minor versions – that last part matters. Pin your torch too far back and MONAI will fail to import in ways that don’t scream “version mismatch.”

CPU-only MONAI is fine for testing transforms or running 2D tile pipelines. The moment you try to run anything volumetric on CPU – a full CT scan, a 3D U-Net – you’re looking at runtimes that make iteration impractical. That’s not a MONAI limitation specifically; it’s just what GPU acceleration buys you in medical imaging.

Pick your install path

Three official routes exist. They’re not equivalent and the docs don’t rank them.

• pip – fastest, cleanest, uses your existing Python. Best if you already have a working PyTorch install.
• Docker – everything preloaded including the right CUDA version. Best for fresh servers or when driver mismatches are already causing headaches.
• Source – needed only if you’re contributing to MONAI or want the unreleased dev branch.

Install MONAI via pip

A clean virtual environment is non-negotiable here. Package pollution from a previous attempt is the single most common reason a MONAI install appears to succeed but then explodes on first import.

python -m venv monai-env
source monai-env/bin/activate # Windows: monai-envScriptsactivate
pip install --upgrade pip
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install 'monai[all]'==1.5.2

That last line is the important one. Plain pip install monai pulls only NumPy and PyTorch – no Nibabel, no ITK, no scikit-image. According to the official installation docs, pip install 'monai[all]' installs all optional dependencies including Nibabel, scikit-image, Pillow, TensorBoard, Ignite, torchvision, ITK, tqdm, lmdb, psutil, and openslide. Skip the extras and code touching a .nii.gz file will throw an opaque module-not-found error six imports deep – and you’ll spend an hour thinking MONAI itself is broken.

Watch out: The [all] bundle pulls openslide and lmdb, which need system-level packages on Linux (e.g., libopenslide-dev) and will fail loudly if those aren’t present. If you don’t need the full dependency set, use targeted extras like monai[nibabel,itk,tqdm] instead.

Install MONAI via Docker

NVIDIA driver installed and Docker 19.03+? One command:

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

The catch: :latest includes the dev branch from GitHub, not just a stable release. For reproducible pipelines, pin the tag explicitly:

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

The --ipc=host flag matters. PyTorch’s DataLoader uses shared memory for worker processes; without host IPC you’ll hit bus errors on multi-worker loading with no useful stack trace.

Which brings up a question worth sitting with before you choose Docker: if your team is already managing GPU environments with conda or virtualenv and everyone has consistent driver versions, does Docker actually reduce complexity here, or does it add a layer you’ll eventually fight? The answer isn’t universal – it depends on your infra. Docker wins clearly on fresh servers and CI pipelines. For a single researcher’s workstation with an already-working CUDA setup, pip is usually less friction.

Verify the install actually works

Two commands. First confirms MONAI imports and reports its version. Second confirms your GPU is visible.

python -c "import monai; monai.config.print_config()"
python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"

The config print-out lists MONAI’s version, PyTorch version, NumPy, and every optional dependency it detected. If Nibabel shows “NOT INSTALLED” and you needed it, that’s your [all] flag mistake surfacing.

The verification quirk nobody documents

If import monai hangs your Jupyter kernel and dies with no traceback – just “The kernel appears to have died. It will restart automatically.” – that’s almost always a torch/CUDA library mismatch, not MONAI itself. Run the same import in a plain terminal Python REPL first. Works there but not in Jupyter? Your notebook is picking up a different Python interpreter. This exact scenario is filed as GitHub issue #5171, reported on Python 3.9.12.

Common install errors

Namespace collision between monai and monai-weekly

Subtle and easy to trigger. The official docs note that coexistence of monai and monai-weekly in the same environment causes namespace conflicts and ImportError – both packages install into the same monai/ folder. This happens when you followed a tutorial using the weekly build, then later ran a plain pip install monai without cleaning up first. The symptom is usually a bogus ImportError on something like LoadNifti or get_config_values – old symbols from one version loaded on top of the other (as reported in GitHub issue #1902).

Fix:

pip uninstall -y monai
pip uninstall -y monai-weekly
pip install 'monai[all]'==1.5.2

PyTorch version out of the support window

MONAI 1.5.2 will happily install against ancient torch and then fail at runtime – there’s no pre-install version check. Verify with pip show torch and cross-reference against the MONAI 1.5.2 requirements file in the repo. More than three minor versions behind current stable? Upgrade torch before touching MONAI.

C++/CUDA extensions failing to build

Source installs with BUILD_MONAI=1 set. On Linux: you need a matching CUDA toolkit installed, not just the driver. On macOS, per the official docs, the command is BUILD_MONAI=1 CC=clang CXX=clang++ python setup.py develop. Don’t need the C++ extensions? Drop BUILD_MONAI=1 entirely – the Python-only path covers 90% of use cases.

Upgrade, downgrade, uninstall

Upgrading between minor versions is usually clean:

pip install --upgrade 'monai[all]'==1.5.2

Downgrading is where people get burned. MONAI’s API evolves – transforms get renamed, class signatures shift. If your codebase targets 1.3 and you install 1.5.2, some imports may break. Read the CHANGELOG before jumping versions.

To fully remove MONAI:

pip uninstall -y monai monai-weekly
rm -rf ~/.cache/torch/hub/checkpoints/ # optional: model cache
docker rmi projectmonai/monai:latest # if you used Docker

Clean that model cache. A fresh install won’t touch it, and a stale checkpoint from an incompatible version will load silently and produce garbage outputs – no warning, no error, just wrong results.

FAQ

Can I use MONAI without a GPU?

Yes, but only for prototyping or 2D pathology tiles. Any real 3D volumetric work needs CUDA.

Should I install monai or monai-weekly?

Stick with the stable release for anything you’ll write papers about or deploy in production. The weekly build (as of the current release cadence, published every Sunday) gets you new features early – useful if you’re waiting on a specific bug fix or a new transform. Just never have both installed simultaneously in the same environment. That’s the fastest path to a broken import, and the fix isn’t obvious when you’re staring at a LoadNifti ImportError at 11pm.

Is MONAI the same as MONAI Deploy and MONAI Label?

No, and this trips up newcomers constantly. MONAI core (what this guide covers) is the training and inference framework. MONAI Label is a server for interactive annotation – separate repo, separate install. MONAI Deploy is a different stack entirely, for packaging models into clinical applications with different dependencies and a different install process. Figure out which one your project actually needs before running any install command; installing the wrong one and then layering the right one on top is a good way to end up with the namespace collision problem described above.

Next step: clone the MONAI tutorials repo and run the Spleen segmentation notebook end-to-end. If it completes without errors, your install is production-ready.