Page history Edit this page How do I edit this website?

Frequently Asked Questions

This page lists answers to the most frequently asked questions.


How do I apply an operation or macro to multiple images?

See the Batch Processing page.

What is the largest size image that ImageJ can open?

There is a 2 gigapixel limit when opening and displaying image planes using the original ImageJ user interface’s default image viewer. However, one major goal of the ImageJ2 project is to break this limit. ImageJ2 uses the ImgLib2 library as its data model, which has much larger limits on the number of pixels (theoretically: ~\(2^{63}\) per dimension, up to ~ \(2^{31}\) dimensions, totaling ~\(2^{63^{31}}\) pixels). Hence, you can open larger images using the ImageJ2 API. But you will not be able to display them in the user interface yet.

Furthermore, the SCIFIO library (what ImageJ2 uses for data I/O) supports opening such images on-demand as “cell images” such that blocks are read from disk as you iterate over the image. This is similar to (but more powerful than) ImageJ’s virtual stacks feature. In this way, you can write code to process these large images without displaying them.

The Fiji project also includes the BigDataViewer (BDV) plugin, which currently functions as an alternative viewer, to display arbitrarily large images backed by ImgLib2. In the future we hope to integrate BDV-driven UI technology more completely into ImageJ2 core. But there are a couple of limitations right now:

  1. BDV was originally designed for large SPIM data; opening large image files more generally currently requires some coding. But we want to change this.
  2. Many ImageJ plugins assume the data is stored in an ImageJ 1.x data structure, which is not what BDV uses. So “mixing and matching” ImageJ and ImageJ2 functionality is tricky here. But we are working to lift these restrictions as time goes on.


See the MacOS page.


How do I launch ImageJ with a different version of Java?

Bundled Java

ImageJ will look for a “bundled” Java in the java subdirectory, in a platform- and architecture-specific directory. For example, if you downloaded the “Windows 64-bit” Fiji it would come with a Java installation in the\java\win64 directory. The possible platform + architecture directories are:

  • win64
  • win32
  • linux-amd64
  • linux
  • macosx

If you replace the Java in the directory appropriate for your platform (or create the indicated subdirectory structure, if you downloaded the “No JRE” Fiji) then ImageJ will try to launch with that “bundled” Java first.

System Java

If no bundled Java is found, ImageJ will fall back to your “system Java”, which is indicated by the JAVA_HOME environment variable. Usually this is set when installing Java, but see also Java environment variable setup.

Command-line option

Finally, ImageJ supports the java-home command-line flag that allows it to be started with a particular Java version for just that run. To use this flag you would run the platform- + architecture-specific launcher (aka “binary” or “excutable”) in the CLI of your choice, with a syntax like:

/path/to/ImageJ/launcher --java-home '/path/to/java'

The ImageJ launcher path would be one of:


On macOS

Old versions of Mac OS X shipped with Apple’s fork of OpenJDK 6, which included some Mac-specific features. But Apple Java is long discontinued now. If you wish to install your own OpenJDK(s) on modern versions of macOS, it is recommended to use Homebrew, or simply download and unpack the OpenJDK distribution(s) of your choice into a Java folder inside your user folder.

See “How do I setup a launcher app” below for instructions on turning this invocation into a Dock icon.

On Linux

One downside of doing this is that ImageJ will launch in a separate process, which has some unintuitive side effects. For example, Ubuntu’s Unity user interface will not allow you to “Pin to Launcher” in this case.

How do I setup a launcher app for macOS for running with a different JVM version?

Start Automator and select to create an Application. Double-click Run Shell Script in the Library/Utilities folder and replace the text content — cat — with the following:

open -a "" --args --java-home \  

Save anywhere you like.

To replace this application’s icon, Get Info on your real Fiji, click on the icon on the top left, press ⌘ Command + C, Get Info on your Fiji Automator app, click the icon, and press ⌘ Command + V.

You will then see two icons in the dock, the one of the launcher app and the one of Fiji when it’s running.

(based on this guide)

What is this headless mode and what do I need it for?

The term headless refers to running ImageJ without a graphical desktop, e.g. on a cluster. See the Headless page for more information.


How can I verify that my ImageJ is really 100% up to date?

ImageJ will report itself as “up to date” as long as all files installed in your ImageJ match the latest versions from the remote update sites. However, there are cases where your ImageJ may report itself as “up to date” but still be missing critical files, or have mismatching versions (e.g., the dreaded NoSuchMethodError).

To be certain, run HelpUpdate…, and click the “Advanced mode” button. Then verify the following View Options:

  • View uninstalled files only: Shows files that are available from remote ImageJ update sites, but not installed in your ImageJ. Consider changing the “Status/Action” to “/downloads” for these items, especially any .jar files that are flagged with “Not installed” status.
  • View locally modified files only: Shows files that have been edited locally (i.e., do not match any version from the remote update sites). Consider changing the “Status/Action” to “Update” for these items, especially any .jar files that you did not intentionally modify.
  • View local-only files: Shows files that are not known at all to the remote update sites. These files were likely added manually (e.g., if you installed additional plugins manually; see “How do I install additional plugins” below). Consider deleting these files if you do not need them, especially any .jar files of unknown origin or conflicting file names.

If you flag any changes to be made, press the “Apply changes” to update your ImageJ. And after restarting ImageJ, you might want to run HelpUpdate… again to make sure everything looks the way you expect!

How do I install additional plugins?

If the plugin is published on an ImageJ update site, you can run HelpUpdate then click Manage update sites to enable it. Not only does this install the plugins for you automatically, but you will also be notified of any updates whenever they are released.

Otherwise, you can drag ‘n drop the .jar files onto the ImageJ window, or use PluginsInstall Plugin… with .jar, .class and .java files, or copy the plugins to and restart ImageJ. See the walk-through with screenshots.

How do I downgrade ImageJ?

Downgrading is generally not recommended as a long-term solution, but can be handy to avoid new bugs that crop up.

If you need to downgrade to avoid a critical bug, please report that bug to the developers so that it can be fixed in a future version!

  • You can change the version of ImageJ used via the HelpUpdate ImageJ… menu item. Note that this only changes the version of ImageJ itself—not any installed extensions. This command also works in ImageJ2, but only changes the version of the embedded ImageJ 1.x, not all ImageJ2 components.
  • You can switch to a different version of Java.
  • You can download a Fiji Life-Line version.

Lastly, if you have not yet upgraded, and have a currently working configuration, you can make a backup copy of your ImageJ folder before upgrading. Then if the upgrade has undesirable consequences, switch back to the old copy.

My plugin runs fine in the Script Editor, but it does not show up in the menus when I install it. What’s wrong?

To be picked up as a plugin, the .jar’s file name must contain an underscore, and it either needs to contain an appropriate plugins.config file or the class name needs to contain an underscore, too.

The safest way to ensure these conventions is to use the FileExport as .jar file menu item.

I tried to update ImageJ via HelpUpdate, but it throws an exception instead?

Please download a fresh copy from here.

I updated ImageJ via HelpUpdate, and now it does not start anymore!

See If ImageJ does not start up on the Troubleshooting page.

The Updater always says Connection refused. Maybe it does not use the proxy?

Indeed, an earlier version of the Updater does not use your system-wide network proxy settings. You can download a new ImageJ to receive the fix. Or you can update the Updater manually like this:

  • open the Script Editor with FileNewScript
  • set the language to BeanShell in the Language menu of the editor
  • paste the following code (and adjust it to match your settings):

    import ij.IJ;

    System.setProperty(“”, “true”);“Update…”);

  • run the script via the Run menu


What is the difference between ImageJ and ImageJ2?

ImageJ is an extensible platform for scientific image analysis. ImageJ2 is redesigned from the ground up to meet the same needs, yet engineered with future-proof flexibility to adapt to researchers’ growing requirements (new data types, higher dimensionality, huge images, etc…).

Will ImageJ macros, plugins and scripts still work in ImageJ2?

Yes. We are completely committed to 100% backwards compatibility with the original ImageJ. ImageJ2 includes the latest version of ImageJ “under the hood” so that existing macros, plugins and scripts will still run the same as before.

ImageJ2 user interfaces are just plugins; ImageJ2 runs with the ImageJ UI by default. But we have also created a new ImageJ2 user interface modeled after the original ImageJ to a very large extent, with all the same shortcut keys and behaviors whenever possible. Either way, ImageJ2 looks and feels like the original ImageJ, but with a powerful new infrastructure allowing it to process a wider variety of image data more quickly and easily.

Does ImageJ2 support the ImageJ macro language? Is it deprecated?

Thanks to the ImageJ legacy layer, ImageJ macros will run unchanged in ImageJ2, while also allowing to harness ImageJ2’s new parameterized scripting paradigm—something that was previously not possible with the macro language.

The ImageJ macro language has been extremely useful to many users. However, it has a substantial limitation: its functions are separate from those available from Java and the other scripting languages.

In ImageJ2, the goal is to provide one unified set of functions, which is fully accessible from Java and all scripting languages. Hence, ImageJ2 plugins and scripts are more flexible than ImageJ plugins and macros. They can run headless on a server, and are accessible from various applications such as CellProfiler, KNIME, OMERO, and headless from the command line. We would encourage newly developed scripts and plugins to use the ImageJ2 API since it offers these advantages, but the ImageJ API will remain accessible, too.

Can I call ImageJ API from an ImageJ2 command?

Yes, although it is not recommended. You will lose most of the advantages of ImageJ2 if you embed calls to ImageJ within your command. The original ImageJ is tightly coupled to AWT and hence does not work well headless. For details, see the Headless page.

Can I call ImageJ2 API from an ImageJ plugin?

Yes, see the call-modern-from-legacy tutorial example.

How do I find equivalent commands between the ImageJ and ImageJ2 APIs?

ImageJ1-ImageJ2 cheat sheet is available.


What is the difference between Fiji and ImageJ?

Fiji is a distribution of ImageJ + ImageJ2: it bundles the core application with a curated selection of plugins pre-installed.

How do I install Fiji?

See here for instructions.

How do I install a Fiji plugin into plain ImageJ?

Doing this is not recommended:

  • Fiji plugin authors test their plugins in Fiji, not plain ImageJ.
  • An increasing number of plugins use features of ImageJ2, which are not available in the original ImageJ.
  • If you install multiple plugins with complex dependency chains in this manner, you may have dependency version conflicts. For things to work, you will need to ensure that all the library versions are compatible. The Fiji maintainers have already solved this problem for the Fiji distribution.

So you could save yourself a lot of pain by using Fiji instead.

That said, you can install a Fiji plugin in a plain ImageJ installation, as long as you copy all its dependencies with it. You can do this as follows:

git clone git://
cd Stitching
mvn dependency:copy-dependencies

Then copy target/dependency/*.jar into your ImageJ installation.

You will need Git and Maven installed for this to work.


How can I call ImageJ from MATLAB, or vice versa?

Use the ImageJ-MATLAB update site. See the MATLAB page for details.


Why do I get a NoSuchMethodError or NoSuchClassDefFoundError when running a rebuilt plugin?

This is most likely caused by version skew, i.e. when an incompatible version of a build dependency is installed. Example: if you build against mpicbg-1.0.0.jar and run that plugin in a Fiji which has only installed mpicbg-0.6.1.jar, the latter might miss some methods or classes, or even contain incompatible class definitions.

To investigate, you can use mvn dependency:copy-dependencies on the command-line (to copy all build dependencies into target/dependency/) and then use your favorite Zip tool to look for the class name mentioned in the exception. In Eclipse, you can simply use ⌃ Ctrl / ⌘ ⌃ Ctrl on a PC ⌘ command on a Mac  + ⇧ Shift + T to look open the respective class; If a recent enough Eclipse is used, and the default settings have not been tampered with, this will start downloading and show the source attached to the dependency.

Once you know which dependency is supposed to contain the class/method, compare the version number of the file(s) in and

Sometimes, classes are contained in multiple .jar files. This is a frequent source of problems e.g. when some developers try to be helpful and include dependencies’ classes into their plugin .jar files. This is a problem because those class files are naturally not updated when the dependency is installed as a proper, separate .jar file and updated. To investigate such issues, use the PluginsUtilitiesFind Jar For Class command in Fiji, to determine which .jar file serves the class you are looking for.

What is Maven, and why did you pick it?

Maven is a system to build .jar files from source code, and to manage dependencies (i.e. it is easy to specify which minimal version of, say, ImageJ is required by the source code).

We picked it because we need a standard way to interact and collaborate with other projects and with each other. For starters, it allows developers to stay with their favorite development environment (Eclipse, Netbeans, IntelliJ, etc).

For details, please refer to our page on Maven.

What is MiniMaven and why did you create it?

Please refer to the MiniMaven and Supported Compilers pages for an explanation.

How do I create a new ImageJ plugin using Maven?

Please refer to our page on Maven.

How do I upload a new release of an ImageJ plugin?

Please refer to the Uploading plugins tutorial.

How do I upload a new release of a core ImageJ library such as ImgLib?

The same way you do a plugin. But it will upload to the ImageJ update site (you can only upload to one update site at a time, though, see also this ticket).

Over the years we evolved a development style as follows:

  • create a topic branch
  • test as much as you need to be comfortable to merge
  • merge
  • deal with any fall-out

This development style has been adopted by the ImageJ2 team, with two additions (making the fall-out step much smaller):

  • tests are added as automated regression tests (to be run by the continuous integration whenever new changes were pushed) whenever possible.
  • merges are usually done with --no-ff, so that even fast-forwarding branches (i.e. rebased on top of master) will get a merge commit in which the branch is described more broadly.

See also coding style.

Class loading issue in 3-rd party libraries (e.g. JPPF)

Libraries trying to load resources or classes with the current thread’s class loader rather than with IJ’s class loader may fail. The solution is to first set the current thread’s class loader to the IJ-classloader. This must be done from the same thread that will later call the problematic code:


How do I see the source code for a command?

ImageJ is open source; as such, it is possible to inspect the source code for any command, in the interest of transparency and reproducibility.

Here are several ways to do so:

  1. Using
    • Go to
    • Type in your search
    • Click the GitHub button!
  2. Using the search bar:
    • Press L to focus the search bar.
    • Type the name of the command.
    • Press ↓ Down to select it.
    • Click the Source button.
    • This will open the source in a browser window.
  3. Using GitHub:
    • Using the search bar, locate your command, taking note of the Class column’s value.
      • E.g., if we type “make binary” we see that the class is ij.plugin.Thresholder.
    • Open the relevant project in GitHub:
      • E.g., for “ij.” classes, go to:
    • Press the T key, and type the name of the file you are looking for.
      • In the example above, this is
    • You should end up with a hit like:
    • This method requires that you know in which repository the code lives. However, you can combine it with method above to figure out which repository, then load the code on GitHub, if desired.
  4. Using the “Open Source for Menu Item” command:
    • Run PluginsScriptingOpen Source for Menu Item.
      • Unfortunately, you must select this from the menu, not using the search bar.
    • Run the command whose source you want to see.
      • E.g., ProcessBinaryMake Binary.
      • Again, select it from the menu directly, not using the search bar.
    • This will open the source in your web browser.

In the future, we plan to make this easier by having one single easy command for viewing the source code.

What are “external” plugins?

As far as users are concerned, external Fiji plugins are exactly the same as internal Fiji plugins. For developers, “external plugin” simply implies that the plugin’s source code is maintained in its own source code repository. For example, TrakEM2 has been an external Fiji plugin since Fiji’s inception.

Where should I put the jars of my plugin?

If you develop a Fiji plugin, the result will be in the form of one or more jars containing your plugin and possibly third-party libraries that you rely on. To deploy your plugin you put the jars in the plugins/ or jars/ Fiji subdirectories. The general idea is that only the jars directly containing plugin classes go into plugins/. Auxiliary and third-party jars go into jars/. (see this mail for more background on this.)

How can I call ImageJ from my software?

If your software is written in Java, we recommend using Maven to structure your project. You can then add dependencies to portions of ImageJ that are of interest to you. See the ImageJ tutorials for examples.

If your software is written in another language such as C or Python, there are many ways to integrate Java functionality. You must choose which one is best for your particular requirements.

To facilitate some use cases, we provide a script for generating a combined bundle of all ImageJ-related JARs in a single uber-JAR library. To use, check out the ImageJ source code and execute:

mvn -Pdeps package

For convenience, we provide a build of this combined JAR file (with suffix -all) from the latest DEVELOPMENT, UNSTABLE version of ImageJ. This build includes the latest changes on the master branch of the source repository. It has not been thoroughly tested and may contain new bugs.

In some cases, use of this JAR file is appropriate and convenient; for example, CellProfiler uses it to integrate with ImageJ. However, you should consider carefully what would be best for your project; see the Uber-JAR page for further information.

Does ImageJ work on mobile devices such as Android?

Not yet as an end-user application. But since Android is a Java-based platform, there is hope. One of the ImageJ2 project’s central design goals was a better separation of concerns, which could make things like an Android version of ImageJ possible. In particular, the core components of ImageJ2 are militant in their avoidance of certain Java SE packages not present in the Android version of Java (which is based on Java ME), such as Java AWT.

That said, ImageJ2 has not even been compile-tested yet using an Android SDK, so there are surely many problems which would need to be resolved. In the future, the ImageJ development team hopes to set up some continuous integration surrounding Android. If you are interested in helping drive this effort forward, please see the android tag on the Forum!

Another possibility for the future is a client/server version of ImageJ that runs in a web browser using HTML5 and JavaScript, which could include cross-platform support for mobile devices (Android, iPhone, tablets, etc.). Again, much groundwork has been done to make the ImageJ2 core design compatible with such an application, but no one has written the server- or client-side yet. If you are seriously interested in helping to pursue such an application, you might also want to check out the OMERO project, which is a client/server application which has some integration with ImageJ.


Why is there Fiji when there is already ImageJ? And what is this ImageJ2 about?

The ImageJ, Fiji and ImageJ2 projects are very closely related. See ImageJ Flavors for a thorough breakdown of the differences.

See also:

In short: we all collaborate, but have slightly different focus, hence the different projects and names.

How can we be sure that ImageJ, ImageJ2 and Fiji aren’t going to diverge or fork over time?

We are working to create an architecture where the programs work together and preserve compatibility. Fiji is just ImageJ with batteries included, and ImageJ2 includes ImageJ as-is for maximum compatibility. Fiji now uses ImageJ2 at its core. Most importantly, all involved developers are strongly dedicated to avoiding divergence—we are working closely together to ensure that ImageJ2 represents a continuation of ImageJ and Fiji, rather than a project fork.

Would it make sense to merge the ImageJ2 and Fiji projects?

Fiji and ImageJ2 are fundamentally the same software, using the same launcher. So from the standpoint of development effort, the ImageJ2 and Fiji projects have indeed merged. ImageJ2 is the core software, and several pieces of infrastructure originally developed for Fiji have now migrated to ImageJ2 (e.g., the Updater, Launcher and Script Editor components). At heart, Fiji is just a big collection of life sciences plugins (though “Fijabcolsp” doesn’t have quite the same ring to it). In other words, Fiji is just an ImageJ update site (“Fijaius”)—and as such, you can obtain a working Fiji installation by downloading ImageJ2, running the updater, and enabling the Fiji update site.

All of that said, we do not want to get rid of the two distinct project names, since people are familiar with both. But we are integrating resources when feasible: e.g., the ImageJ wiki serves all ImageJ content including Fiji-specific content (which is marked with the Fiji logo). But we want to ensure it is clear that ImageJ is not a life-sciences-specific project, whereas Fiji is. Historically, because Fiji has a life sciences focus, there have been some users who refused to switch from the original ImageJ to Fiji even though Fiji makes users’ lives easier in lots of ways. With ImageJ2, we want to avoid such misconceptions.

More effort is still needed to clarify web resources, to explain concisely and clearly where people should go in different circumstances. We also have plans to make bug reporting simpler and easier across the projects.

This is a Wiki but I cannot edit it! Why?

To make changes, you need a GitHub account. Then you can click the “Edit this page” link at the top right corner of any page.

The Wiki is lacking documentation about X, Y and Z

Please feel free to enhance the Wiki! We are thankful for all contributions!

How do I find more information about Command X?

Try searching for the command in ImageJ’s search bar, and clicking the Help button. Alternately, check this wiki: you can use its search bar above, or visit the list of extensions page, which includes links to many documentation pages of ImageJ’s various extensions.

If documentation is missing for the command you’re interested in, you can always view the source directly:

  1. Jump to the search bar (Shortcut: L)
  2. Filter to the command you’re interested in.
  3. The `File` column will tell you the plugin where the desired command is contained.
  4. You can then use this information to find the source code on GitHub - for core ImageJ or Fiji plugins.
  5. From the appropriate project on GitHub, you can find the repository corresponding to the desired plugin.
  6. Finally, you can search for the actual file for the command of interest (Shortcut: T).

As a complete example, if you were interested in the 2D Histogram command:

I have a problem that is not covered on this page!

If you have an issue that is not mentioned here, you might want to ask on one of the mailing lists, or via IRC, or enter a bug report.

How to report issues?

Please see Report a Bug’ %}. While private mail might seem more desirable sometimes, but it is almost always inferior to the open process we established in ImageJ. For starters, bug reporters are unlikely to know who would be the best person to address the issue.

I reported an issue, but it is still not fixed! Why not?

ImageJ and its variants are open source community projects. The list of contributors is large but many of the people involved are not paid to work on it. We greatly value community contributions and assistance.

There are not many professional developers whose formal jobs include responding to and addressing bug reports. These developers are not paid solely to fix bugs—rather, they are working to solve scientific problems and to advance the software’s capabilities. And their attention is spread thin across many projects: ImageJ, Fiji, SCIFIO, SciJava, LOCI, OME, ImgLib2, OpenSPIM, and others.

The organizations above total over 300 source code repositories, many of which have dozens of open issues in their issue trackers. There are also several hundred tickets in the old ImageJ2 issue tracker that were never migrated to GitHub Issues, as well as over a hundred open issues archived in the Fiji Bugzilla.

So please understand that just because we have not responded to a bug report, does not mean we are uninterested in fixing it. It’s just that we are very busy, and can use all the help we can get!

If you want to increase the chances of your issue being worked on, you can:

See the bug reporting best practices article for details.

How do I contribute a bug fix or patch, or propose an idea for a change?

See the Contributing page!


Why do you program in Java? Is C++ not much faster?

See the Philosophy page!

With Oracle buying Sun and Apple deprecating Java, does Java have a future?

Yes. Java is one of the most popular programming languages and still one of the top choices for high-performance, cross-platform applications. Oracle is unlikely to attempt to “kill” Java, but even if they tried they probably couldn’t—OpenJDK is open source and there is a massive community of Java developers behind it. Now that Apple is partnering with Oracle and the OpenJDK community, we are likely to see Java on macOS get better, not worse. Java’s popularity will eventually wane, but not because of any company’s actions now. Rather, as with any programming language, new technologies will emerge and gain popularity, over a course of many years.

Why does ImageJ still target Java 6?

As of June 2014, around 19% of macOS systems still run version 10.6 Snow Leopard or older 1. (In December 2013, it was around 25%.) Unfortunately, Apple and the OpenJDK developer community decided to target OS X 10.7 Lion and above for Java 7 and 8. For the time being, to avoid abandoning older machines which cannot be upgraded from Snow Leopard, ImageJ continues to target Java 6.

Furthermore, updating the required version to a newer version of Java would necessitate improvements to the ImageJ Updater such that it could also update the bundled version of Java, which would be a substantial undertaking. Otherwise, most existing installations of ImageJ would stop working, and those users would need to download ImageJ from scratch again.

See this mailing list thread for further details.

How are you addressing the fact that with increased modularity comes increased complexity?

See the Philosophy page!

How about a version of ImageJ for the web browser, mobile devices, etc.?

While a pure web version of ImageJ would be desirable for a number of reasons, there are several substantial challenges with current technology. In particular, it would be difficult for a Javascript-based ImageJ to maintain compatibility with existing plugins, macros and scripts. For now, our goal is to continue improving the Java version of ImageJ, while remaining cognizant of developments in the web applications domain, to reduce the difficulties of a web version at some future date.

We are developing ImageJ with a careful eye toward modularity, avoiding gratuitous dependencies—particularly on AWT, which is not available on most mobile devices. We hope this approach makes it easier to port ImageJ to additional platforms in the future.

A shorter term pragmatic solution would be an ImageJ web client that connects to a remote server running ImageJ in headless mode, which does the heavy lifting. See also the OMERO project.

Why is open software vital to science?

See the Open Source page!

Is Java still free and open source? I heard Oracle is charging for Java now!

Java is still free and open source. The only reason to pay Oracle for a Java license is to continue receiving commercial support from Oracle after January 2019 for the Oracle version of Java 8. If you use OpenJDK, you are fine. If you use an older version of Oracle Java 8 (such as the one currently shipping with Fiji), you are fine. See this article for details.