Skip to content
Use ImageJ from Python
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.travis Travis: make leading whitespace consistent Dec 16, 2018
imagej Dump Java stack traces in debug mode Apr 10, 2019
test Create a run_plugin function Dec 3, 2018
.gitignore Update gitignore to reflect project rename Dec 2, 2018
.mailmap Add mailmap for better "git shortlog -nse" Dec 3, 2018
.travis.yml Travis: see if Python 3.7 works Dec 12, 2018
AUTHORS.rst Add Michael Pinkert to authors list Dec 3, 2018
LICENSE.txt rebase to Mar 23, 2018 Fix manifest Dec 2, 2018 README: add note about Java 8 vs. 11 Mar 22, 2019
environment.yml Clean up dependency list and CI installation Dec 2, 2018
setup.cfg Prepare Python client for pypi Mar 17, 2017

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.


The recommended way to install pyimagej is with Conda:

conda config --add channels conda-forge 
conda install pyimagej openjdk=8

The above installs it with OpenJDK 8; if you leave off the openjdk=8 it will install OpenJDK 11 by default, which should also work, but is less well tested and may have more rough edges.


Quick start

See this Jupyter notebook.

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.

You can’t perform that action at this time.