Use ImageJ from Python
Clone or download

Python wrapper for ImageJ

pyimagej provides a set of wrapper functions for integration between ImageJ and Python.

It also provides a high-level entry point imagej.IJ for invoking ImageJ Server APIs; see "ImageJ Server" below for details.


Install dependencies using conda env create -f environment.yml.

See also:


Creating the ImageJ gateway

Newest available version

If you want to launch the newest available release version of ImageJ:

import imagej
ij = imagej.init()

This invocation will automatically download and cache the newest release of net.imagej:imagej.

Explicitly specified version

You can specify a particular version, to facilitate reproducibility:

import imagej
ij = imagej.init('2.0.0-rc-68')

With graphical capabilities

If you want to have support for the graphical user interface:

import imagej
ij = imagej.init(headless=False)

Note there are issues with Java AWT via Python on macOS; see this article for a workaround.

Including ImageJ 1.x support

By default, the ImageJ gateway will not include the legacy layer for backwards compatibility with ImageJ 1.x. You can enable the legacy layer as follows:

import imagej
ij = imagej.init('net.imagej:imagej+net.imagej:imagej-legacy')

Including Fiji plugins

By default, the ImageJ gateway will include base ImageJ2 functionality only, without additional plugins such as those that ship with the Fiji distribution of ImageJ.

You can create an ImageJ gateway including Fiji plugins as follows:

import imagej
ij = imagej.init('sc.fiji:fiji')

From a local installation

If you have an installation of ImageJ2 such as Fiji, you can wrap an ImageJ gateway around it:

import imagej
ij = imagej.init('/Applications/')

Replace /Applications/ with the actual location of your installation.

Using the ImageJ gateway

Once you have your ImageJ gateway, you can start using it. Here is an example:

# Import an image with scikit-image.
import skimage
from skimage import io
# NB: Blood vessel image from:
img = io.imread('')
import numpy as np
img = np.mean(img, axis=2)

# Invoke ImageJ's Frangi vesselness op.
vessels = np.zeros(img.shape, dtype=img.dtype)
ij.op().filter().frangiVesselness(,, [1, 1], 20)

See also test/ for other examples of usage.

ImageJ Server


The imagej.server module has its own requirements:

  • requests is required to communicate with the ImageJ server.
  • pillow is required for the function. In addition, display or xv must be available to view the image.


There is a short usage example here.