Skip to main content

Python wrapper for ImageJ

Project description

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.


  1. Install Conda:

  2. Activate the conda-forge channel:

    conda config --add channels conda-forge
    conda config --set channel_priority strict
  3. Install pyimagej into a new conda environment:

    conda create -n pyimagej pyimagej openjdk=8
  4. Whenever you want to use pyimagej, activate its environment:

    conda activate pyimagej

Installation asides

  • If you want to use scikit-image in conjunction, as demonstrated below, you can install it also via:

    conda install scikit-image
  • The above command installs pyimagej 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.

  • It is possible to dynamically install pyimagej from within a Jupyter notebook:

    import sys
    !conda install --yes --prefix {sys.prefix} -c conda-forge pyimagej openjdk=8
  • If you would prefer to install pyimagej via pip, more legwork is required. See this thread for hints.


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.

With more memory available to Java

Java's virtual machine (the JVM) has a "max heap" value limiting how much memory it can use. You can increase the value as follows:

import scyjava_config
import imagej
ij = imagej.init()

Replace 6g with the amount of memory Java should have. You can also pass other JVM arguments.

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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pyimagej, version 0.5.0
Filename, size File type Python version Upload date Hashes
Filename, size pyimagej-0.5.0-py2-none-any.whl (8.9 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size pyimagej-0.5.0.tar.gz (9.4 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page