---
id: roifile
version: "2026.7.30"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# roifile — Read and write ImageJ ROI format

License: permissive · Maintenance: active · Downloads: 119.8K/mo

## What it is and what it does

Roifile is a Python library for working with ImageJ ROI files, an undocumented format used by ImageJ to store regions of interest, geometric shapes, paths, and text annotations for image overlays. It lets you read ROI data from .roi files, ZIP archives, or embedded in TIFF metadata; create new ROI objects programmatically from coordinate arrays; modify ROI properties like type, size, and labels; and write the results back to disk or TIFF files. The package depends only on numpy at runtime, with optional support for tifffile (to embed ROIs in TIFF files), imagecodecs (for certain image types), and matplotlib (for plotting overlays).

The library is designed for scientific and image-analysis workflows where you need to programmatically manipulate or batch-process ImageJ annotations. It includes a command-line viewer to inspect ROI files and full round-trip support—you can read a ROI, modify it, and write it back with the same format and properties preserved. The format itself has limitations: integer coordinates are constrained to the range -5000..60536, and the implementation follows ImageJ's Java reference implementation for compatibility.

Use it for:

- Batch convert or migrate ImageJ ROI annotations between .roi, ZIP, and TIFF formats
- Programmatically create geometric annotations (points, polygons, paths) and embed them in TIFF images for ImageJ
- Read and modify ROI metadata (names, types, display properties) in automated image-processing pipelines
- Extract coordinate data from ImageJ overlays for downstream analysis or visualization in other tools
- View and inspect ROI file contents from the command line without opening ImageJ

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Read, write, create, and plot ImageJ ROI format files, which store regions of interest, geometric shapes, paths, and text overlays for image annotation.

Yes. The package is actively maintained, has no known vulnerabilities, installs with minimal friction, and solves a specific and well-defined problem for anyone working with ImageJ ROI files in Python. The permissive BSD-3-Clause license poses no restrictions. Install it if you need to read, write, or manipulate ImageJ annotations programmatically.

## Install

pip install roifile
uv add roifile
poetry add roifile

## Installing roifile

Before you install: Low install friction with a single runtime dependency (numpy). Active maintenance with a release 15 days old; the package has been in development since 2020 and currently supports Python 3.12–3.15.

License in practice: BSD-3-Clause is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install roifile

from roifile import ImagejRoi

roi = ImagejRoi.frompoints([[1.1, 2.2], [3.3, 4.4]])
roi.tofile('output.roi')

roi_read = ImagejRoi.fromfile('output.roi')
print(roi_read.coordinates())

Requires Python 3.12 or later; numpy must be installed as a runtime dependency.

Verify before relying:

- Whether optional dependencies (tifffile, imagecodecs, matplotlib) are required for specific use cases or fully optional
- Performance characteristics when handling large ROI collections or complex geometric shapes

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 119.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

imagej roi format reader, roi file parser python, image overlay annotation, imagej roi writer, geometric shape storage, region of interest handling, image-annotation, imagej-compatible, scientific-imaging

[View on SkillFed](https://skillfed.io/packages/roifile) · [View on PyPI](https://pypi.org/project/roifile/)