Install MONAI 1.5.1: NVIDIA Medical AI Setup Guide

By the end of this guide, you’ll have MONAI 1.5.1 running on a GPU, verified with a real config dump, and know exactly which failure mode to look for when it doesn’t. The tricky part isn’t the install command – it’s picking the right one out of three, and avoiding the silent CPU fallback that turns your NVIDIA medical AI rig into an overpriced laptop.

MONAI is the PyTorch-based framework for deep learning in medical imaging. It’s developed by NVIDIA, NIH, and King’s College London, licensed under Apache 2.0 – and there’s an arXiv paper (2211.02701) if you want the theoretical framing. This article is not that.

Pick your install method before you type anything

There are three real options. They’re not equivalent, and the official docs list them without saying which one you should actually use (as of 2025).

Think of these three paths like choosing between a pre-built workstation, a kit computer, and fabricating your own motherboard. Docker ships with everything already wired up. pip gives you the parts – but one critical component (GPU-enabled PyTorch) doesn’t come in the box. Source is for people who already know what’s in every box.

If you’re deploying MONAI for actual GPU inference or training, Docker is the least painful path. According to the MONAI 1.5.1 installation guide, you need the NVIDIA driver and Docker 19.03+ on your Linux host, but you don’t need to install the CUDA toolkit on the host itself – the container brings its own. That single detail saves you from about half of the CUDA-mismatch issues that show up in the MONAI GitHub tracker.

System requirements (honest version)

• OS: Linux is the tested target. Windows works via WSL2 + Docker Desktop, macOS works for CPU-only.
• Python: 3.9+ recommended for 1.5.x (matches PyTorch’s support window).
• PyTorch: As of 2025, MONAI supports the current PyTorch version plus three previous minor versions. MONAI 1.5.x adds PyTorch 2.6 support.
• GPU: MONAI Label documentation (as of 2025) recommends a medium/high-end NVIDIA GPU with 16-24 GB video RAM for local runs; CPU works but performance is poor. The same rule of thumb applies to core MONAI training jobs.
• Disk: ~5 GB for the Docker image, plus whatever your datasets need (medical volumes can run into hundreds of GB).

Install MONAI with Docker (recommended)

Assuming NVIDIA driver + Docker + NVIDIA Container Toolkit are already in place:

# Quick sanity check that GPUs are visible to Docker
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu20.04 nvidia-smi

# Pull and enter the MONAI container
docker run --gpus all --rm -ti --ipc=host projectmonai/monai:latest /bin/bash

# Inside the container:
python -c "import monai; monai.config.print_config()"

The 1.5.1 version tag gives you a pinned milestone image if you’d rather not track latest – swap it in like projectmonai/monai:1.5.1. The --ipc=host flag is required for multi-worker DataLoaders; omitting it can cause cryptic shared-memory errors at runtime.

Install MONAI with pip (and the trap nobody warns you about)

The pip route looks simpler:

python -m venv monai-env
source monai-env/bin/activate
pip install --upgrade pip setuptools wheel
pip install 'monai[all]'

The [all] extra pulls every optional dependency – nibabel, itk, pytorch-ignite, tensorboard, and about twenty others. Skip it and you’ll hit missing-module errors the first time you load a NIfTI file.

Now the trap. The MONAI 1.5.1 docs state explicitly that the install commands above “usually end up installing CPU variant of PyTorch.” To get GPU-enabled PyTorch you have to install the NVIDIA driver, check PyTorch’s guide for the right CUDA version, install CUDA manually, and set CUDA_PATH before installing PyTorch. If you skip that, everything looks installed. Imports work. Then your training loop runs at 3% GPU utilization because Torch is on CPU.

The fix is boring but non-negotiable: install PyTorch first, from PyTorch’s official selector, with the correct CUDA build for your driver, and only then pip install monai.

Verify the install actually works on GPU

The one-liner every tutorial shows you:

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

This prints version info, but it does not confirm GPU access. Add this second check:

python -c "import torch; print('CUDA:', torch.cuda.is_available(), '| Device:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU-only')"

If the first command prints a MONAI version and the second prints your GPU name – you’re done. If it says CPU-only, you’re in the pip trap from the previous section.

Pro tip: Before running any real MONAI workload, do a 60-second smoke test: load a MedNIST batch, push it to cuda, run one forward pass, and check nvidia-smi in another terminal shows non-zero GPU-Util. It catches the silent-CPU-fallback bug in under a minute.

Common errors pulled from real GitHub issues

These are the three you’ll actually hit.

1. ImportError from monai + monai-weekly clash

If both monai and monai-weekly end up in the same environment, you get namespace conflicts and an ImportError on import monai – flagged in GitHub issue #1902 and documented in the official MONAI install guide. Common cause: you tried the weekly build to test a feature, then reinstalled stable without uninstalling weekly. Fix:

pip uninstall -y monai monai-weekly
pip install monai

2. Torch detects no GPU despite nvidia-smi working

A failure pattern reported in monai-deploy-app-sdk Discussion #460: torch 2.1.0 cannot detect GPU with CUDA 11.7 and silently falls back to CPU inference; pinning torch==2.0.1 with the same CUDA 11.7 toolkit resolved it. If you’re on an older CUDA runtime and a newer Torch, either upgrade CUDA or pin Torch down. Don’t split the difference.

3. “no kernel image is available for execution on the device”

This bites users whose PyTorch build was compiled for an older set of GPU architectures and doesn’t include support for newer cards. The mismatch shows up at runtime, not install time – everything installs cleanly. Fix: reinstall PyTorch with a build that targets your card’s compute capability, or use a current NGC base image like nvcr.io/nvidia/pytorch:23.03-py3 or later.

Upgrading from an older MONAI

Coming from 1.3.x or 1.4.x? Two things matter. First: the 1.5 branch enables PyTorch 2.6, bumps the torch minimum to address CVE-2024-31580 and CVE-2024-31583, and adds numpy 2 compatibility – so any pinned torch version below that minimum will break. Second: deprecated APIs from 1.4 are gone in 1.5. Check your training scripts before upgrading.

pip install --upgrade monai
# or for the container:
docker pull projectmonai/monai:1.5.1

If you pinned torch for the CUDA 11.7 workaround described above, verify your pin still satisfies MONAI 1.5’s minimum requirement before running the upgrade.

Clean uninstall

pip install: pip uninstall -y monai (or monai-weekly if that’s what you had). Source install: from the cloned directory, run python setup.py develop --uninstall per the official docs. Docker: docker rmi projectmonai/monai:latest. MONAI typically caches downloaded models and bundles under ~/.monai/ and torch hub data under ~/.cache/torch/hub/ – delete those manually if you want a clean slate.

Worth pausing here for a second: the proliferation of install paths (pip, weekly, source, Docker, plus the deploy and label sub-projects) is a real maintenance challenge for a framework at this stage. If you’re setting up MONAI for a team, documenting which path you chose and why will save someone hours later. The choice isn’t just technical – it’s institutional.

FAQ

Can I run MONAI without a GPU?

Yes. CPU-only works fine for development on a laptop and small 2D inference. Anything 3D or training-related: don’t bother.

Is MONAI the same as MONAI Deploy or MONAI Label?

No – three separate repos in the Project-MONAI org with their own version cycles. Core MONAI is the training/inference framework covered here. MONAI Label is the annotation tool that plugs into 3D Slicer. MONAI Deploy is the app packaging and clinical workflow layer. You install core MONAI first regardless; the others sit on top of it. MONAI Deploy in particular has strong opinions about CUDA runtime versions that don’t always match your host setup, so treat it as a separate install project.

Why does my Docker container say GPU device 0 not found?

Nine times out of ten: missing --gpus all in the docker run command, or the NVIDIA Container Toolkit isn’t installed on the host. Run docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu20.04 nvidia-smi first – if that fails, MONAI has nothing to do with your problem.

Next: pull the MedNIST notebook from Project-MONAI/tutorials, mount it into your running container with -v $(pwd):/workspace, and run the first three cells. Under two minutes on GPU means your install is production-ready.