A napari plugin to keep images and annotations as a re-loadable project

License PyPI Python Version tests codecov napari hub

This napari plugin allows to define projects consisting of multiple images that can be annotated with labels and rectangular regions of interest (rois). Those rois can then be exported as series of cropped images and labels, typically to train Machine Learning models. Projects can be easily reopened in order to browse through images and their annotations. This package is a meant to be a light-weight plugin which does not introduce any specific dependencies and that should be easily installable in any environment already containing napari and other plugins.


To start a project, you can just drag and drop files in the file list area. This prompts for the selection of a project folder. After that, more files (also from different folders) can be dragged and dropped to be included in the project. Files can optionally be copied to the project folder but this option has to be set before adding files. When selecting a file in the list, it is opened (using the default image reader or a reader plugin if installed) and two layers, one for rois, and one for annotations are added.

Adding rois

After selecting the rois layer, you can add rectangular rois to the image. If you need square rois of a specific size (as often needed in DL training) you can select the Fixed roi size option and then use the Add roi button. Note that currently only 2D rois are supported. If you work with nD images, the roi is therefore added to the current selected 2D plane.

Adding annotations

After selecting the annotations layer, you can add annotations to your image. There are no restrictions here and you can e.g. add as many labels as you need.

Info storage

All relevant information on project location, project files and rois is stored in a yaml file Parameters.yml. Annotations are stored as 2D tiff files in the annotations as files named after the original files. Note that at the moment if multiple files have the same name, this will cause trouble. This parameter file is used when re-loading an existing project.

Exporting rois

Once you are satisfied with your annotations and rois, you can use the rois to export only the corresponing cropped rois of both the image and annotation layers. For this you can head to the Export tab. Here you can set the location of the export folder, set the names of the folders that will contain cropped images and cropped annotations, and finally set the prefix names for these two types of files. Files are exported as tif files.


You can install napari-annotation-project via pip (note yet functional):

pip install napari-annotation-project

To install latest development version :

pip install git+


Contributions are very welcome. Tests can be run with tox.


Distributed under the terms of the BSD-3 license, "napari-annotation-project" is free and open source software.


If you encounter any problems, please file an issue along with a detailed description.


  • 0.1.1

Last updated:

  • 01 November 2023

First released:

  • 01 November 2023


Supported data:

  • Information not submitted

Plugin type:

GitHub activity:

  • Stars: 11
  • Forks: 3
  • Issues + PRs: 1

Python versions supported:

Operating system:


  • numpy
  • PyYAML
  • scikit-image

Sign up to receive updates