roifile - Read and write ImageJ ROI format

2026.2.10 verified Fri May 01 auth: no python

roifile is a Python library for reading and writing ImageJ ROI (Region of Interest) files. It supports the native ImageJ ROI binary format (.roi) and can extract ROIs from ZIP archives. Current version is 2026.2.10, with a release cadence of roughly monthly updates. Requires Python >=3.11.

pip install roifile

Common errors

error AttributeError: module 'roifile' has no attribute 'roiread' ↓

cause roiread was renamed to roifile.roiread in version 2022.0.0 or import path confusion.

fix

Use: from roifile import roiread

error ValueError: Unsupported ROI type: 0 ↓

cause The ROI file is corrupted or not a valid ImageJ ROI.

fix

Verify the file is a valid .roi file; try re-saving from ImageJ.

Warnings

gotcha roiread() returns a single ImagejRoi object; if your .roi file contains multiple subregions (e.g., composite ROI), it may raise an error or return unexpected results. Use ImagejRoi.fromfile() for complex files. ↓

fix Use roifile.ImagejRoi.fromfile('file.roi') which handles multi-part ROIs.

breaking Version 2024.x changed subpixel coordinates to be represented as floats by default. Older code expecting integer coordinates may break. ↓

fix Access coordinates via roi.coordinates(subpixel=False) to get integer arrays if needed.

deprecated roifile.roi2dict() and roifile.dict2roi() are deprecated and will be removed in a future version. ↓

fix Use ImagejRoi properties directly or json serialization via roi.tojson() and ImagejRoi.fromjson().

Imports

roifile
wrong
```
from roifile import roiread
```
correct
```
import roifile
```
roiread is not a top-level function; use roifile.roiread() or roifile.ImagejRoi.fromfile()
roifile.roiread
```
from roifile import roiread
```
Correct import for the convenience function
roifile.ImagejRoi
```
from roifile import ImagejRoi
```
Main class for ROI objects

Quickstart

Reads an ImageJ ROI file, prints its type and coordinates, then creates a new ROI from a list of points and saves it.

import roifile

# Read an ROI from a file
roi = roifile.roiread('example.roi')
print('ROI type:', roi.roitype)
print('Coordinates:', roi.coordinates())

# Create a new ROI and save
import numpy as np
new_roi = roifile.ImagejRoi.frompoints(np.array([[0,0], [10,0], [10,10], [0,10]]))
new_roi.tofile('square.roi')