nnU-Net v2.8.0 Install Guide: Medical Image Segmentation

Here’s an unpopular take: most nnU-Net install failures aren’t nnU-Net’s fault – they’re PyTorch mismatch failures dressed up as install errors. If you follow the README top-to-bottom, you’ll almost certainly hit them. This guide assumes you already know what nnU-Net does. The goal is to get v2.8.0 deployed cleanly, with the right ResEnc preset, and past the traps that make people rage-quit on day one.

The current release is nnunetv2 2.8.0, published June 7, 2026. Everything below is written against that version.

What you actually need on the machine

Inference works on modest hardware. Training does not – ignore the “works on a laptop” talk. Per the official installation instructions, a GPU with at least 10 GB VRAM is required for training, and 6 CPU cores / 12 threads is the bare minimum CPU. Popular non-datacenter options are the RTX 2080ti, RTX 3080/3090, or RTX 4080/4090.

Linux is the primary target, though Windows and macOS are both supported. Before you pick a Mac, know this: as of v2.8.0, Apple MPS does not implement 3D convolutions, so on M1/M2 devices 3D workloads fall back to CPU. For medical volumes, that’s a non-starter.

The PyTorch trap (read this before you pip install anything)

The official docs shout about this in all-caps, and they’re right to. Do not just pip install nnunetv2 without properly installing PyTorch first – that’s a direct quote from the installation instructions.

Why does it matter? Turns out pip’s dependency resolver doesn’t care about your CUDA driver version. Issue #2386 is the clearest example: during install, nnunet uninstalled a working torch 1.9.1+cu111 and replaced it with torch 2.3.1 – which broke CUDA on an HPC cluster stuck on an older driver. If your CUDA toolkit is pinned by your sysadmin, pip will happily upgrade torch and destroy your environment without a single warning.

The fix is order-of-operations. Install PyTorch first, matched to your CUDA (or MPS/CPU). Then install nnU-Net.

# 1. Create an isolated env
conda create -n nnunet python=3.10 -y
conda activate nnunet

# 2. Install PyTorch FIRST (pick the CUDA that matches your driver)
# See https://pytorch.org/get-started/locally/ for your exact command
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 3. THEN install nnU-Net
pip install nnunetv2

If you want to modify the source – adding custom trainers, tweaking planners – install from git instead:

git clone https://github.com/MIC-DKFZ/nnUNet.git
cd nnUNet
pip install -e .

HPC environments specifically: Before running pip install nnunetv2, pin your torch version in a constraints.txt file and pass -c constraints.txt. Pip will then refuse to silently upgrade torch even if nnU-Net’s pyproject.toml asks for a newer version. It’s the cleanest way to protect a shared cluster environment.

First-run configuration: three folders, one export

nnU-Net splits its working data across three directories: raw inputs, preprocessed tensors, and trained model weights. You tell it where they live via environment variables – nnUNet_raw, nnUNet_preprocessed, and nnUNet_results.

# Add to ~/.bashrc or ~/.zshrc so they persist
export nnUNet_raw="/data/nnUNet_raw"
export nnUNet_preprocessed="/data/nnUNet_preprocessed"
export nnUNet_results="/data/nnUNet_results"

Think of nnUNet_preprocessed as the hot path. During training, every batch pull comes from there. Put it on your fastest disk – NVMe if you have one. A slow disk here will bottleneck GPU utilization in a way that’s easy to miss if you’re only watching nvidia-smi.

That three-folder split is also what makes it possible to share a single preprocessed dataset across multiple training runs without re-running the fingerprint extraction step. Useful if you’re experimenting with different planners on the same data.

Verify it actually works

All nnU-Net commands install with an nnUNetv2_ prefix. Quick sanity check:

# Should print version and available flags
nnUNetv2_train -h

# Confirm PyTorch still sees your GPU (this is the check that saves you)
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"

If that second line prints False after installing nnU-Net, torch got clobbered. Go back to the PyTorch step.

Pick the right planner – the default isn’t the recommended one anymore

The catch is that running nnUNetv2_plan_and_preprocess without arguments gives you the classic planner – and the tool itself flags this: “INFO: You are using the old nnU-Net default planner. We have updated our recommendations. Please consider using those instead.” Most tutorials never mention that warning exists.

The current recommendation is the Residual Encoder presets, introduced in the 2024 paper nnU-Net Revisited. The ResEnc presets – M, L, and XL – automatically adapt batch and patch sizes to hit specific VRAM budgets. Match the preset to your card:

• ResEnc M – similar budget to the standard U-Net (fits 10-12 GB cards)
• ResEnc L – for 24 GB cards (3090/4090)
• ResEnc XL – for 40 GB+ (A100)

# Use the M preset explicitly:
nnUNetv2_plan_and_preprocess -d 1 --verify_dataset_integrity -pl nnUNetPlannerResEncM

# Then train
nnUNetv2_train 1 3d_fullres 0 -p nnUNetResEncUNetMPlans

Better accuracy isn’t free. A community report on discussion #2296 clocked ResEnc L at roughly 300 seconds per epoch versus 75 seconds for standard 3d_fullres on the same dataset – about 4× slower. No official benchmark confirms that ratio, but it’s consistent enough across community reports to plan around before committing to a full training run.

Tune data-augmentation workers (the hidden performance dial)

If you’ve ever watched GPU utilization sag to 30% mid-training and wondered why – this is usually it. nnU-Net spawns CPU workers to feed augmented batches to the GPU. Too few and the GPU starves. Too many and the OS kills them silently when RAM pressure spikes, which causes training to hang with no error message at all.

The official docs list per-GPU values that almost no tutorial repeats: 10-12 workers for the RTX 2080ti, 12 for the RTX 3090, 16-18 for the RTX 4090, and 28-32 for the A100.

export nnUNet_n_proc_DA=16 # example for a 4090

Small dial. Big difference on training throughput.

Common errors and what actually fixes them

Three failures show up over and over in the issue tracker.

1. Training hangs with no error message. Per the common problems doc, this is usually the OS silently killing a background worker because it was about to run out of RAM – not GPU memory. Monitor system RAM during training. If it’s full, reduce nnUNet_n_proc_DA to lower the worker count. The n_proc_DA table above gives you a safe starting point for your GPU.

2. CUDA out of memory during training. Drop to a smaller ResEnc preset. nnU-Net’s patch size is determined at planning time based on your declared VRAM budget – retrying without re-planning won’t help.

3. Could not build wheels for nnunet. You’re installing the old v1 package (nnunet), not nnunetv2. Different PyPI package. Check your command.

Upgrading

pip install -U nnunetv2 – that’s usually it. The data folders survive in place.

Upgrading from v1 is a different story. Dataset folder layouts changed between versions, so migrating a v1 project requires converting the directory structure manually. Check the official migration docs for the current conversion command, since the exact flags may have changed since this was written.

If you’re citing this work in a paper, the primary reference is Isensee et al., “nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation,”Nature Methods, 2021. If you’re using ResEnc presets specifically, the 2024 nnU-Net Revisited paper has its own citation.

Does the performance gap between ResEnc L and standard 3d_fullres hold across dataset sizes and modalities, or is the 4× epoch-time figure specific to the dataset in that community report? The official team hasn’t published a cross-dataset benchmark for this comparison yet – which is worth keeping in mind if you’re making a hardware procurement decision based on it.

FAQ

Can I run inference-only without a GPU?

Yes. CPU inference works – it’s just slow. For a single 3D volume, expect minutes rather than seconds. Apple Silicon routes 3D convolutions through CPU too, same result.

Which ResEnc preset should I actually pick for a first project?

Start with ResEnc M. Here’s the scenario: you have a 12 GB card, a moderate dataset, and no established baseline yet. M trains in reasonable time, fits your hardware, and the 2024 paper shows it’s competitive with larger models on most benchmarks. Only move to L after you have a working M baseline and your validation metrics are clearly plateauing – otherwise you’re spending 4× the training time chasing marginal Dice improvements. XL is A100-class hardware and large public challenge territory.

What image formats does nnU-Net v2 support?

v2 expanded format support beyond NIfTI, but the complete list of supported readers and any version-specific caveats is best checked in the current installation-and-setup docs rather than taken from a third-party guide – this is an area that has changed across minor versions and may continue to do so.

Next step: point nnUNet_raw at a small public dataset (Task04_Hippocampus from the Medical Segmentation Decathlon is fast to download), run nnUNetv2_plan_and_preprocess -d 4 --verify_dataset_integrity -pl nnUNetPlannerResEncM, and watch the fingerprint extraction complete. That’s the moment you know your install is healthy.