This notebook is part of the PyImageJ Tutorial Series, and assumes familiarity with the ImageJ API. Dedicated tutorials for ImageJ can be found here.

1 Starting ImageJ from Python

The pyimagej module enables access to the entire ImageJ API from Python in a natural way.

Let’s initialize an ImageJ gateway including Fiji plugins, at a reproducible version:

import imagej

# initialize ImageJ
ij = imagej.init('sc.fiji:fiji:2.14.0')
print(f"ImageJ version: {ij.getVersion()}")
ImageJ version: 2.14.0/1.54f

1.1 Ways to initialize




Newest available version of ImageJ2 w/ ImageJ support

ij = imagej.init()


Specific version of ImageJ2 w/ ImageJ support

ij = imagej.init('2.14.0')


Interactive (newest version)*

ij = imagej.init(mode='interactive')


Interactive (specific version)*

ij = imagej.init('net.imagej:imagej:2.14.0', mode='interactive')


Without support for original ImageJ (newest versions)

ij = imagej.init('net.imagej:imagej', add_legacy=False


With Fiji plugins (newest version)

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


With Fiji plugins (specific version)

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


From a local installation

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


*: mode='interactive' is unavailalbe on macOS. Instead use mode='gui'. When set to gui mode the Python interpeter is blocked and no longer interactive. Check out the initialization documentation for more information.

1 pyimagej uses jgo internally to call up ImageJ, so all of these initializations are tied to the usage of jgo. You can read up on the usage of jgo to find out more about this initialization.

2 Reproducible means code is stable, executing the same today, tomorrow, and in years to come. While it is convenient and elegant to depend on the newest version of a program, behavior may change when new versions are released—for the better if bugs are fixed; for the worse if bugs are introduced—and people executing your notebook at a later time may encounter broken cells, unexpected results, or other more subtle behavioral differences. You can help avoid this pitfall by pinning to a specific version of the software. The British Ecological Society published Guide to Better Science: Reproducible Code diving into the relevant challenges in more detail, including an R-centric illustration of best practices. A web search for reproducible python also yields several detailed articles.

1.2 The ImageJ2 gateway

The ImageJ2 gateway is the object interface that lets you use ImageJ-related features (see This gateway contains all of the regular ImageJ2 Java functions. PyImageJ also adds a module of convenience functions under For example, converting a numpy array to an ImageJ2 dataset:

import numpy as np

array = np.random.rand(5, 4, 3)
dataset =

Operating in headless mode - the original ImageJ will have limited functionality.
(3, 4, 5)

1.3 Increasing the 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 it:

import imagej
import scyjava
ij = imagej.init()

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

Without having specified the max heap value explicitly, here is how much memory this notebook’s JVM has available:

'ImageJ2 2.14.0/1.54f; Java 11.0.15-internal [amd64]; 35MB of 7952MB'