A GUI for nnU-Net and nnInteractive-powered annotation that keeps the entire workflow in one place.

• nnU-Net Workflow: train, validate and apply nnU-Net on images that already have labels.
• Annotation Workflow: for images without labels. Create labels efficiently with nnInteractive and scribbles, then train, validate and improve the model in iterations.

Installation · Quick start · CLI · AI agents · Q&A · Documentation · Citation · License

Why nnWorkbench

• Everything in one place: All your datasets with their images, labels, preprocessed data, trained models and validation results, connected in one window, from the first image to the final prediction.
• nnInteractive and nnU-Net, connected: Create labels with nnInteractive in Napari, save them directly as nnU-Net training data, and continue with preprocessing and training without any conversion.
• Guidance along the way: Each stage shows what is done, what can run next and what has to be fixed first, with a short how-to on every page and a step-by-step guide built in.
• Inspection at every stage: Open raw images and labels, preprocessed data, predictions and validation results in Napari, with the matching files loaded together, and find the weakest cases with one click.
• Simple by default, full control when needed: nnWorkbench works for users of every experience level. Short dialogs with sensible defaults get you going; planners, trainers and additional arguments are there when you need them, and every step can be copied as the exact nnU-Net command for a terminal or a cluster.

Why Annotation Workflow

No labels yet? The Annotation Workflow gets you from raw images to a trained model with as little manual work as possible:

• Annotate smart, not hard: Label only parts of many images instead of everything in a few (sparse labels): nnInteractive outlines a whole 3D object in a few clicks, scribbles cover the rest.
• Improve in iterations: Train early, see where the model fails, and annotate exactly there.
• Made for sparse labels: A trainer bundled with nnWorkbench learns from sparse labels and is selected automatically.
• Guided from start to finish: A built-in guide explains every step, from defining your classes to deciding when the model is good enough.

Installation

Requirements:

• Python 3.12
• Windows 10/11, macOS 13 or newer, or Linux with glibc 2.35 or newer (e.g. Ubuntu 22.04+)
• Conda or another Python environment manager
• For training: an NVIDIA GPU, 24 GB of memory for the recommended setup, 8 GB at minimum with a smaller planner (see Planners and GPU Memory in the guide). Annotating, validating and predicting also work without one.

From PyPI:

conda create -n nnworkbench python=3.12
conda activate nnworkbench
pip install "nnworkbench[all]"
nnworkbench-gui

From source:

conda create -n nnworkbench python=3.12
conda activate nnworkbench
git clone https://github.com/MIC-DKFZ/nnWorkbench.git
cd nnWorkbench
pip install -e ".[all]"
nnworkbench-gui

Depending on your system, you may need to install PyTorch manually before installing nnWorkbench, as described on pytorch.org. This is required on Windows to use an NVIDIA GPU. For a lightweight installation without the GUI on a remote machine, and for notes on using nnWorkbench on macOS, see the instructions below.

Windows

pip installs a CPU-only PyTorch on Windows, so an NVIDIA GPU would not be used. Install the CUDA build of PyTorch before nnWorkbench, in the activated environment:

pip install torch --index-url https://download.pytorch.org/whl/cu128

If a CPU-only PyTorch is already installed, add --force-reinstall (pip keeps the installed version otherwise); the Info dialog of the GUI (top right) shows this command when the GPU is not usable.

Then install nnWorkbench from PyPI:

pip install "nnworkbench[all]"

or from source (inside the cloned repository):

pip install -e ".[all]"

The right command for your CUDA version is on pytorch.org. These installation commands work in PowerShell and the Windows command prompt. Commands that nnWorkbench shows or copies (Copy command) are written for PowerShell (as for bash and zsh on Linux and macOS), not for the command prompt.

macOS

nnWorkbench itself runs fully on macOS (13 or newer). For the GPU-heavy parts, it relies on nnU-Net and nnInteractive, which differ on Apple silicon:

• nnU-Net (training and prediction): runs on the Apple GPU with -device mps (choose MPS under Device in the Train and Predict dialogs). It works, but is much slower than an NVIDIA GPU, and the GPU shares its memory with the system: prefer nnUNetPlannerResEncM or ExperimentPlanner over nnUNetPlannerResEncL. A Mac is fine for predicting and short test runs; train on a GPU machine or cluster.
• nnInteractive (annotation): the napari-nninteractive plugin uses only CUDA GPUs, so on a Mac it runs on the CPU, which is slow. For a smooth experience, connect the plugin to an nnInteractive server on a GPU machine (see the napari-nninteractive documentation).

Remote machines and clusters

On a cluster, the core installation is enough: nnU-Net, the bundled trainers and the command-line tools, without the nnWorkbench GUI, Napari or nnInteractive.

# from PyPI
pip install nnworkbench

# from source (inside the cloned repository)
pip install -e .

Save the nnU-Net folders on the remote machine once:

nnworkbench-set-paths --raw /path/to/nnUNet_raw --preprocessed /path/to/nnUNet_preprocessed --results /path/to/nnUNet_results

nnworkbench-run then uses them for nnU-Net commands and dataset tools. Optionally, you can prepare this in the nnWorkbench GUI: on the overview, add a remote path profile with the folders of the remote machine; Export then copies the nnworkbench-set-paths command above with these paths. The commands themselves can also be configured in the GUI: Copy command in the run dialogs gives the matching nnworkbench-run command, which uses the paths saved on the remote machine. The GUI does not need the cluster's data for this: plans that are only preprocessed on the cluster, and models or folds that only exist there, can be chosen or typed in the Train and Predict dialogs. The run button then stays disabled, and Copy command gives the command for the cluster. All commands and dataset tools for the remote machine are listed in the CLI overview.

Troubleshooting

• Windows, preprocessing or prediction fails with Unable to open … for reading or Error while creating the NDArray: a folder path contains non-ASCII characters (e.g. C:\Users\Jürgen\…), which nnU-Net cannot use on Windows. Move the nnU-Net folders (and prediction input/output folders) to a path with ASCII characters only, e.g. C:\nnUNet\nnUNet_raw, and set them again. nnWorkbench marks such folders in red.
• No matching distribution found for mitk-python: the environment does not use Python 3.12, or the system is too old (macOS below 13, Linux with glibc below 2.35). Create the environment with python=3.12; on older Linux systems, use the core installation (pip install nnworkbench) without the GUI.
• Info shows CPU only although there is an NVIDIA GPU: PyTorch was installed without CUDA support or does not match the driver; Info shows the cause and the fix.
• Qt 5 instead of Qt 6: install the GUI without a Qt binding and add PyQt5: pip install "nnworkbench[gui]" PyQt5 (from source: pip install -e ".[gui]" PyQt5).

Quick start

Start the GUI with nnworkbench-gui.

1. Set your folders. On the overview, select three folders: nnUNet_raw for your datasets (images, labels and dataset.json), nnUNet_preprocessed for the preprocessed data used in training, and nnUNet_results for the trained models and their validation results. nnU-Net fills the last two. Empty folders are fine. nnWorkbench lists every dataset it finds in them.
2. Create a dataset or select an existing one. Click ＋ New dataset, or open a dataset from the list. Put your images into imagesTr (and, if you have them, your labels into labelsTr), and describe the classes with Edit next to dataset.json. Red badges on the Data page tell you what is still missing.
3. Annotate (Annotation Workflow only). On the Data page, click the pencil next to an image, annotate in Napari with nnInteractive or the brush, and click Save annotation. Labels can be dense (every voxel is labelled; the mask starts as background, e.g. to segment a single organ with nnInteractive) or sparse (you annotate only parts of each image; the rest stays ignore and is not used for training). For sparse labels, add an ignore class with the highest ID to dataset.json.
4. Preprocess. On Preprocess, click ▶ Preprocess… and then ▶ Preprocess, or Copy command to run it on a remote machine. The defaults are a good start.
5. Train. On Train, click ▶ Train…, choose the folds and click ▶ Train, or Copy command to run it on a remote machine. The console at the bottom shows the progress.
6. Validate. On Validate, click a fold of your model to see its Dice score per case, sort by Dice to see the weakest cases first, and open any case in Napari to compare the prediction with your label.
7. Iterate (Annotation Workflow only). Where the model is still wrong, start another iteration: select the dataset on the overview and click ＋ New iteration. It copies the images and labels into a new dataset (or links the images, to save space); continue there with step 3 and annotate where the model fails.
8. Predict. On Predict, choose a folder of new images and an output folder and click ▶ Predict, or Copy command to run it on a remote machine.

Every page has a short how-to on the left, and ? Guide in the top bar opens the full nnWorkbench guide. It explains both workflows step by step: how to understand your images, define classes, annotate efficiently, read the validation results, and decide when a model is good enough.

CLI overview

nnWorkbench can be used entirely through the GUI. If you prefer not to use the GUI, or are working on a remote system, the same workflows are available from the command line.

After configuring the paths with nnworkbench-set-paths, use nnworkbench-run to run any nnU-Net command with those saved paths:

nnworkbench-run nnUNetv2_plan_and_preprocess -d 42 -c 3d_fullres -pl nnUNetPlannerResEncL --verify_dataset_integrity
nnworkbench-run nnUNetv2_train 42 3d_fullres 0 -p nnUNetResEncUNetLPlans
nnworkbench-run nnUNetv2_predict -i /path/to/input -o /path/to/output -d 42 -c 3d_fullres -p nnUNetResEncUNetLPlans

These use the recommended nnUNetPlannerResEncL, which the GUI also preselects. For sparse annotations from the Annotation Workflow, add -tr nnUNetTrainerBetterIgnoreSampling to training and prediction.

It also provides the following dataset tools:

# List the datasets in the nnU-Net folders: ID, name, where they exist and the iteration (add --json)
nnworkbench-run list

# Create a dataset with imagesTr, labelsTr and dataset.json (add --ignore for sparse labels)
nnworkbench-run create-dataset -d 42 --name CellSegmentation --labels background,cell,nucleus --ignore --channels fluorescence

# Add dataset-description.md: a template to describe the images and define the classes (also: create-dataset --add-description)
nnworkbench-run describe -d 42

# Show what is done and what is next for a dataset, and the device (GPU / MPS / CPU) (add --json for scripts)
nnworkbench-run status -d 42

# The command the GUI would prefill for preprocess, train or predict, and why each option was chosen
nnworkbench-run suggest -d 42 --step train

# Validation results: Dice per fold and class, and the weakest cases first (as the Validate page; add --json)
nnworkbench-run validation -d 42
# ... and open a validation case in Napari: image, label and prediction
nnworkbench-run validation -d 42 --open cells_017

# Open predictions with their input images in Napari
nnworkbench-run inspect-predictions /path/to/output --images /path/to/input

# Start the next iteration: copy images, labels and dataset.json into a new dataset
nnworkbench-run new-iteration -d 42

# Open a dataset's images and labels in Napari, starting at a case (or -i 12 for the 12th image)
nnworkbench-run inspect -d 42 --case cells_012

# Annotate a case in Napari with nnInteractive (as the pencil in the GUI; saves to labelsTr)
nnworkbench-run annotate -d 42 --case cells_012

# Compute statistics (as on the Data page): classes per image and voxels per class, from labelsTr
nnworkbench-run compute-statistics -d 42 --workers 4

# Stack naturally ordered 2D slices (e.g. TIFF or PNG) into one 3D NIfTI volume
nnworkbench-run stack-images /path/to/image_slices --file-type .tif --spacing 1 1 1

# Remove everything a trained model folder does not need for prediction, e.g. before sharing (in place, cannot be undone)
nnworkbench-run reduce-checkpoints /path/to/nnUNet_results/Dataset042_CellSegmentation/MODEL_FOLDER --yes

Add --json to any tool that returns a result for machine-readable output, e.g. for scripts or agents. Steps that cannot be undone ask for confirmation: reduce-checkpoints and training a fold that already has results need --yes; add --dry-run to see what would happen without changing anything. -d (or --dataset) specifies the numeric nnU-Net dataset ID under the saved nnUNet_raw path. For example, use -d 42 for Dataset042_CellSegmentation. Run nnworkbench-get-paths to view the saved path configuration, and add --help to any tool to see all its options.

Work with an AI agent

nnWorkbench is ready for AI coding agents such as Claude Code or Codex. Open the repository (or your working folder with it) in the agent and describe your goal, e.g. "Help me train a model that segments the nuclei in my microscopy images in /data/images." The agent follows AGENTS.md: it asks about your images and labels in plain words, sets up the dataset, runs preprocessing and training, and summarises the results. You do what needs your eyes and expertise: it opens the images for you to annotate and the predictions for you to check, and continues when you are done.

Q&A

Do I need a GPU?

For training, an NVIDIA GPU is strongly recommended; on the CPU, training takes days per fold. Everything else (managing datasets, annotating, inspecting, validating, predicting) also works without one. Info (top right in the GUI) shows which device was found.

I already use nnU-Net. Can I use my existing datasets and models?

Yes. nnWorkbench works directly on the standard nnU-Net folders: choose your existing nnUNet_raw, nnUNet_preprocessed and nnUNet_results on the overview, and all datasets, plans and trained models appear. Nothing is converted or moved.

Are my data and trained models still compatible with nnU-Net?

Yes. Datasets, preprocessed data and models stay in the standard nnU-Net folders and formats, and every step runs a regular nnU-Net command, so you can continue with nnU-Net alone at any time. Models trained with the bundled nnUNetTrainerBetterIgnoreSampling need this trainer for prediction: use nnworkbench-run nnUNetv2_predict …, or make the model usable with plain nnU-Net via nnworkbench-run reduce-checkpoints MODEL_FOLDER --reset-trainer-name --yes, which removes what prediction does not need and sets the trainer to nnUNetTrainer.

Can I train on a cluster and keep working in the nnWorkbench GUI on my computer?

Yes. Use the core installation on the cluster (see Remote machines and clusters above) and copy the commands from the GUI (see the CLI overview). If the cluster's nnUNet_results folder is mounted on your computer, the GUI shows the training progress and the validation results as if they ran locally. If it is not mounted, you can still configure training and prediction in the GUI: enter the plans, trainer, configuration and folds that exist on the cluster, and copy the command.

Where does my data have to be for a remote setup?

Each step needs the folder written by the previous one on the machine that runs it: preprocessing needs nnUNet_raw, training needs nnUNet_preprocessed, and prediction needs the model in nnUNet_results. The GUI on your computer uses nnUNet_raw for annotating and nnUNet_results for validation. The simplest setup is storage both machines can access, e.g. a mounted network drive; otherwise copy nnUNet_raw to the remote machine after each iteration and copy nnUNet_results back.

Which file formats are supported?

The formats nnU-Net reads: for 3D images .nii.gz / .nii (recommended), .nrrd, .mha, .gipl and .tif / .tiff; for 2D images .png, .bmp and .tif. JPEG is not supported, because its lossy compression alters the images. All images and labels of a dataset use the same file ending, set in dataset.json. A folder of 2D slices can be combined into one 3D volume with nnworkbench-run stack-images (see the CLI overview); more in the guide under Prepare Your Images.

Does nnWorkbench work with 2D images?

Yes. The nnU-Net Workflow works the same for 2D and 3D images. The Annotation Workflow also works with 2D images, but annotate them with scribbles (the brush in Napari): nnInteractive does not work on 2D images. Preprocessing, training, validation and prediction with nnU-Net work in any case.

Can I annotate with nnInteractive without a local GPU?

Yes. nnInteractive can run on a server with a GPU, while you annotate in Napari on your computer. Set up the server and connect the plugin as described in the napari-nninteractive documentation. Without a GPU or a server, nnInteractive runs on the CPU, which is slow (on a Mac always, see macOS above).

Documentation

The nnWorkbench guide explains both workflows step by step, with the matching command for each step. It is also built into the GUI: ? Guide in the top bar and More in the guide · … on every page.

• Setup: nnU-Net folders, remote machines, creating a dataset and dataset.json.
• 1. Describe and 2. Define: understanding your images, defining classes, dense or sparse labels.
• 3. Annotate: annotating efficiently with nnInteractive and scribbles.
• 4. Train: preprocessing, planners and GPU memory, trainers, folds and device.
• 5. Validate: inspecting predictions, metrics, typical errors and the next iteration.
• 6. Predict: applying and sharing a trained model.

For AI agents: AGENTS.md guides an agent (e.g. Claude Code or Codex) through the whole process with CLI commands, and tells it where you take over (annotating, looking at results).

Underlying tools:

• nnU-Net and its documentation: dataset format, planners, trainers and everything below nnWorkbench.
• nnInteractive: the interactive 3D segmentation model behind the annotation.
• napari-nninteractive: the Napari plugin for nnInteractive, including an nnInteractive server for annotating without a local GPU.

Citation

If nnWorkbench helps your research, please cite it together with the methods you used: nnInteractive for the annotation, nnU-Net for preprocessing, training and prediction. The software citation is also in CITATION.cff (Cite this repository on GitHub).

nnWorkbench:

Krämer, L., Isensee, F., Maier-Hein, K. H., & Dreher, K. K. (2026). nnWorkbench (Version 0.1.0) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.24013948

BibTeX

@software{nnworkbench2026,
  author  = {Krämer, Lars and Isensee, Fabian and Maier-Hein, Klaus H. and Dreher, Kris K.},
  title   = {nnWorkbench},
  version = {0.1.0},
  year    = {2026},
  doi     = {10.5281/zenodo.24013948},
  url     = {https://github.com/MIC-DKFZ/nnWorkbench}
}

nnInteractive (annotation):

Isensee, F.*, Rokuss, M.*, Krämer, L.*, Dinkelacker, S., Ravindran, A., Stritzke, F., Hamm, B., Wald, T., Langenberg, M., Ulrich, C., Deissler, J., Floca, R., & Maier-Hein, K. (2025). nnInteractive: Redefining 3D Promptable Segmentation. https://arxiv.org/abs/2503.08373
*: equal contribution

BibTeX

@article{isensee2025nninteractive,
  author  = {Isensee, Fabian and Rokuss, Maximilian and Krämer, Lars and Dinkelacker, Stefan and Ravindran, Ashis and Stritzke, Florian and Hamm, Benjamin and Wald, Tassilo and Langenberg, Moritz and Ulrich, Constantin and Deissler, Jonathan and Floca, Ralf and Maier-Hein, Klaus},
  title   = {nnInteractive: Redefining 3D Promptable Segmentation},
  journal = {arXiv preprint arXiv:2503.08373},
  year    = {2025},
  url     = {https://arxiv.org/abs/2503.08373}
}

nnU-Net (preprocessing, training and prediction):

Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2021). nnU-Net: a self-configuring method for deep learning-based biomedical image segmentation. Nature Methods, 18(2), 203-211.

BibTeX

@article{isensee2021nnunet,
  author  = {Isensee, Fabian and Jaeger, Paul F. and Kohl, Simon A. A. and Petersen, Jens and Maier-Hein, Klaus H.},
  title   = {{nnU-Net}: a self-configuring method for deep learning-based biomedical image segmentation},
  journal = {Nature Methods},
  volume  = {18},
  number  = {2},
  pages   = {203--211},
  year    = {2021},
  doi     = {10.1038/s41592-020-01008-z}
}

nnU-Net Revisited (the residual encoder planners, including the default nnUNetPlannerResEncL):

Isensee, F., Wald, T., Ulrich, C., Baumgartner, M., Roy, S., Maier-Hein, K., & Jaeger, P. F. (2024). nnU-Net Revisited: A Call for Rigorous Validation in 3D Medical Image Segmentation. MICCAI 2024. https://arxiv.org/abs/2404.09556

BibTeX

@inproceedings{isensee2024nnunetrevisited,
  author    = {Isensee, Fabian and Wald, Tassilo and Ulrich, Constantin and Baumgartner, Michael and Roy, Saikat and Maier-Hein, Klaus and Jaeger, Paul F.},
  title     = {{nnU-Net} Revisited: A Call for Rigorous Validation in {3D} Medical Image Segmentation},
  booktitle = {Medical Image Computing and Computer Assisted Intervention -- MICCAI 2024},
  year      = {2024},
  url       = {https://arxiv.org/abs/2404.09556}
}

License

nnWorkbench is licensed under the Apache License 2.0.

Note: The nnInteractive model weights, downloaded on first use for interactive annotation, are licensed under CC BY-NC-SA 4.0: non-commercial use only. nnU-Net and the rest of nnWorkbench are not affected.

Acknowledgements

    

This repository is developed and maintained by the Applied Computer Vision Lab (ACVL) of Helmholtz Imaging.