nnU-Net v2

2.7.0 verified Fri May 01 auth: no python

nnU-Net is a self-adapting framework for biomedical image segmentation that automatically configures itself for new datasets. Version 2.7.0 reworks the dataset conversion and introduces new training modes. Active development, monthly releases.

pip install nnunetv2

Common errors

error ModuleNotFoundError: No module named 'nnunetv2' ↓

cause Package not installed or environment not activated.

fix

Run pip install nnunetv2 or pip install nnunetv2[all] in your environment.

error RuntimeError: The environment variable nnUNet_raw is not set! ↓

cause Required environment variables are missing.

fix

Set nnUNet_raw, nnUNet_preprocessed, and nnUNet_results before importing any nnU-Net modules.

error AssertionError: The dataset.json does not contain a 'labels' key with proper structure. ↓

cause Dataset JSON does not follow v2 format (labels must be a dict mapping old to new label names).

fix

Use convert_MSD_dataset or manually update dataset.json per the documentation.

error ValueError: Plans identifier 'nnUNetPlans' not found. ↓

cause Planning step either wasn't run or produced no output.

fix

Run plannner.plan_and_preprocess() before training. Verify the plans file exists in nnUNet_preprocessed/DatasetXXX.

Warnings

breaking From v2.0, the environment variables nnUNet_raw_data_base and nnUNet_preprocessed are replaced by nnUNet_raw, nnUNet_preprocessed, and nnUNet_results. Old scripts will break. ↓

fix Set new env vars: nnUNet_raw, nnUNet_preprocessed, nnUNet_results. Update scripts that used the old names.

breaking The dataset JSON format changed. The 'labels' field now uses a dictionary for old label names to new ones, and the 'modality' field must be a dict. ↓

fix Update dataset.json to follow the new schema. See https://github.com/MIC-DKFZ/nnUNet/blob/master/documentation/dataset_format.md

deprecated The use of 'nnUNet_compile' flag is deprecated. Use PyTorch's torch.compile directly. ↓

fix Replace nnUNet_compile=True with torch.compile(model) in your training script.

gotcha Training on Windows may fail due to the default CUDA memory allocation policy or path length limits. Linux is the only officially supported OS. ↓

fix Use Linux (Ubuntu) or WSL2. Ensure short paths (e.g., C:\nnunet).

gotcha nnU-Net v2 no longer supports multi-GPU training via nnUNet_train. Use PyTorch DDP manually. ↓

fix Run training with torchrun: torchrun --nnodes=1 --nproc_per_node=4 --master_port=xxxx nnunetv2/run/run_training.py ...

Install

pip install nnunetv2[all]

Imports

nnUNetPlanner

wrong

from nnunet.experiment_planning import nnUNetPlanner

correct

from nnunetv2.experiment_planning.plan_and_configurator import nnUNetPlanner

v1 package is nnunet; v2 requires nnunetv2 prefix

nnUNetTrainer

wrong

from nnunet.training import nnUNetTrainer

correct

from nnunetv2.training.nnUNetTrainer import nnUNetTrainer

Import path changed between major versions

nnUNetPredictor

wrong

from nnunet.inference import predict

correct

from nnunetv2.inference.predict import nnUNetPredictor

Predictor class was added in v2

Quickstart

Prepares environment variables, converts a Medical Segmentation Decathlon dataset, plans preprocessing, and runs a 2D training fold.

import os
os.environ['nnUNet_raw'] = '/path/to/nnUNet_raw'
os.environ['nnUNet_preprocessed'] = '/path/to/nnUNet_preprocessed'
os.environ['nnUNet_results'] = '/path/to/nnUNet_results'
# Convert dataset (Task002_Heart example)
from nnunetv2.dataset_conversion import convert_MSD_dataset
convert_MSD_dataset.convert_msd_dataset('/path/to/Task02_Heart')
# Plan & preprocess
from nnunetv2.experiment_planning.plan_and_configurator import nnUNetPlanner
planner = nnUNetPlanner(dataset_name_or_id='002', plans_identifier='nnUNetPlans')
planner.plan_and_preprocess()
# Train 2D U-Net
from nnunetv2.run.run_training import run_training
run_training('002', '2d', 0, plans_identifier='nnUNetPlans')