Frequently Asked Questions

Revision as of 04:01, 13 March 2015 by Schindelin (talk | contribs) (Development: new question: how to investigate NoSuchMethodErrors?)




This problem usually arises when 12-bit or 14-bit images are loaded into ImageJ without autoscaling. In that case, they are treated as if they were 16-bit images, and therefore the dynamic range is all wrong. You can fix this by clicking on Image>Adjust>Brightness/Contrast... and hitting the Auto button.



You can override the autoscaling using the Brightness/Contrast dialog.


Because the full range of values is typically much less than the maximum—e.g., in the case of a 12-bit detector the actual maximum range is 0-4095, and often even smaller in practice—ImageJ performs autoscaling to show you a meaningful or "pretty good" image by default, which is not just a black square (see previous question). That is: it maps the darkest actual intensity in your data to black, and the brightest actual intensity in your data to white. You can override this mapping using the Brightness/Contrast dialog under the Image>Adjust menu (shortcut: Shift+C).

Alternately, to disable autoscaling during initial import, you can use the Bio-Formats plugin to import your data with the "Autoscale" option turned off:

  • File > Import > Bio-Formats
  • Choose your file
  • Uncheck the "Autoscale" box
  • Click OK

Further reading:

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

See the Batch Processing page.

Mac OS X

Why does ImageJ crash frequently?

This is most likely an AWT issue with Apple's version of Java 6. There is even a bug in our bug tracker about it. The problem is that we did not manage to find a work-around because the bug appears to be in the MacOSX-specific part of the Java Virtual Machine that was provided by Apple. It seems to be related to opening new windows while mouse updates are processed, though. If you have this issue, or find out what causes it, please comment on this bug report.

How do I set up Java 6 on OS X?

Newer versions of OS X come without Java installed, and only Java 8 is available from




How do I run ImageJ on Yosemite?

There is a known issue where Java 6 is required on OSX. As Java 6 is no longer shipped with Yosemite this creates problems.

There is a fix currently in testing. You can replace the file with an updated version. Please make sure the updated version is still marked as executable. If this fixes the problem for you, please comment on GitHub or send us a mail to let us know that it worked.

If the updated launcher does not work for you, as a temporary workaround you can install Java 6.


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

On Windows

Install Java 7, and delete or rename the\java and/or\jre folders, if they exist.


Use the --java-home command line option:

/Applications/ --java-home \

On Linux

Use the --java-home command line option:

$HOME/ --java-home \





Save anywhere you like.



(based on this guide)



How do I avoid running out of memory (OutOfMemoryError)?

The first thing to do is make sure that ImageJ has a large enough "maximum heap" size:

  • Edit > Options > Memory & Threads
  • Change "Maximum Memory" to something larger (at most, 1000 MB less than your computer's total RAM).


If you are already at the limits of your computer's physical memory, the next step would be to add more.

About Java garbage collection: Java always automatically calls the garbage collector when the heap is getting full [1]. While it is possible to manually invoke the garbage collector by clicking ImageJ's status bar—or programmatically by calling run("Collect Garbage") in a macro or System.gc() in a plugin—it will not solve the fundamental problem of Java actually not having a sufficient amount of memory. (The only exception to this is a rare case where Java decides that garbage collection is happening too slowly, in which case you should see the message "GC overhead limit exceeded" [2]).

Why does ImageJ not release any memory back to the system?

This is a characteristic of the Java runtime. In many cases, Java never releases memory back to the system, so memory monitors such as Windows Task Manager will always report an ever-growing amount of RAM used by the Java process, until the JVM shuts down.

The best way to monitor ImageJ's actual memory usage is to run the Monitor Memory... command. You can also click on the ImageJ status bar to trigger a garbage collection operation, which will typically decrease the memory use.

That said, some articles suggest that you can cause Java to give back free memory to the OS under certain conditions; see:

To be clear, Java does reuse memory when you close and reopen images. The behavior described above is not a memory leak per se. In my lab we leave ImageJ running for days or weeks at a time doing batch processing and it works just fine.

See also:

How do I run ImageJ in debug mode?

See Debugging intro#Launching ImageJ in debug mode.




To be certain, run Help > Update, and click the "Advanced mode" button. Then verify the following View Options:


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 Help > Update 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 Help > Update then click the Manage update sites button 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 Plugins>Install Plugin... with .jar, .class and .java files, or copy the plugins to and restart ImageJ. See the walk-through with screenshots.



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

I tried to update ImageJ via Help>Update, but it throws an exception instead?

The easiest way to get back a functional updater is to import this URL via File>Import>URL....



I updated ImageJ via Help>Update, and now it does not start anymore!

You may have been bitten by a bug in the updater that is already fixed (but you did not get the fix in time). Please follow these instructions.



Alternatively, you can update the updater manually like this:

  • open the Script Editor with File>New>Script
import ij.IJ;

System.setProperty("", "true");"Update Fiji");
  • run the script via the Run menu

I updated to Ubuntu 11.04 and now I no longer see the Title bar when I close ImageJ

I can no longer move any windows or use the X button on the title bar to close them (the window decorations all disappear).

If you are really on Ubuntu 11.04, an update should fix the problem. If you are not on Ubuntu 11.04, or if the update does not fix the problem, please read on for possible workarounds.

This is not a ImageJ problem but a bug in the NVIDIA driver. One solution is described in:

Edit (as root) the file /etc/X11/xorg.conf and add the following 2 options in Section "Device" before the EndSection line:

  Option "AddARGBVisuals" "True"
  Option "AddARGBGLXVisuals" "True"

The above eases the problem but does not completely solve it. The solution will be an updated driver from NVIDIA when it is available. If you choose to remain with Unity or Ubuntu Classic, you may log out and then log in again when the problem appears. You can also restart the window manager without logging out by running

  compiz --replace &

in a terminal. This restores the window decorations but all windows from all virtual desktops end in the first one.

Another solution is to install Unity-2D and choose it when you log in. This seems to work well. It also solves a number of general display problems.


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



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




Can I call ImageJ1 API from an ImageJ2 command?


Can I call ImageJ2 API from an ImageJ1 plugin?



How do I install Fiji?


How do I turn my ImageJ installation into a Fiji one?

Fiji is just ImageJ. If you are running ImageJ2, simply run Help > Update, click Manage update sites, and enable the Fiji update site.


How do I develop Fiji in Eclipse?

Please refer to the page Developing Fiji in Eclipse.

How can I build Fiji from the command-line?



Doing this is not recommended:




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


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

3D Viewer

The 3D Viewer opens a window saying An unexpected exception occurred.

If in the same window, it also says:

java.lang.NullPointerException:Canvas3D: null GraphicsConfiguration

the reason is most likely that your graphics setup does not have any hardware 3D acceleration. This can happen e.g. when you run ImageJ via a remote X11 connection (3D acceleration works only when the graphics are displayed on the same machine as the program runs).

Unfortunately, there is not workaround/fix for this situation yet, except to use ImageJ locally when you want to use the 3D Viewer.

Problem with Intel graphics cards

There is a known problem with older Windows drivers for some Intel graphics cards. Usually, this is fixed by installing new drivers. If you would like to help make ImageJ nicer by detecting faulty driver versions, please contact us.

The 3D Viewer simply crashes

Unfortunately, there are quite a large number of possible reasons. Please help us by debugging the issues and contacting us (mailing list or IRC) with the information. You can also report a bug, which will provide a lot of additional, potentially useful information.

Only a gray rectangle is shown by the 3D Viewer

As with 3D Viewer crashes, there are quite a large number of possible reasons. Please help us by debugging the issues and contacting us (preferably via mailing list) with the information. You can also report a bug, which will provide a lot of addidtional, potentially useful information.

I have a compile error building the 3D Viewer regarding a class Appearance

If you get an error similar to this:

Building plugins/3D_Viewer.jar <- src-plugins/3D_Viewer/ImageJ_3D_...
src-plugins/3D_Viewer/customnode/ cannot find symbol
symbol  : class Appearance
location: package

it means that you do not have Java3D installed. This happens typically when you have an environment variable JAVA_HOME set to an existing JDK without Java3D. Try setting JAVA_HOME to a JDK with Java3D available. If you have write permissions to the path JAVA_HOME points to, you could install Java3D manually.


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

If you are looking to call ImageJ code from your MATLAB script, it is actually quite simple. Just embed the calls to fully qualified Java class methods directly in your scripts. MATLAB takes care of transparently converting between Java primitive types and arrays and its own matrices and cell structures. The Fiji distribution of ImageJ provides a helper program called Miji to simplify this approach even further. See the Miji page for further details.

Conversely, if you are looking to evaluate MATLAB code from within an ImageJ plugin or other Java code, MATLAB provides an interface called JMI for doing it. However, for it to work, you must launch your program from inside the MATLAB environment, so that it runs with MATLAB's JVM.







What is Maven, and why did you pick it?



For details, please refer to our page on Maven.

What is MiniMaven and why did you create it?


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 our tutorial how to upload files.



What is the recommended way to develop in ImageJ?

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



See also coding style.




How do I see the source code for a command?


Here are several ways to do so:

  1. Using the Command Finder:
    • Press L for the Command Finder.
    • Type the name of the command.
    • Press to select it.
    • Click the Source button.
  2. Using's search:
    • This will automatically perform a search throughout all code known to for that source file. If there are multiple matches, you will see them all. Clicking on a match opens it in the gitweb interface.
      • You can find this code by typing:
      • Scripts written in other languages work similarly.
  3. Using GitHub:
    • Open the relevant project in GitHub:
      • 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 the search method above to figure out which repository, then load the code on GitHub, if desired.
    • Run Plugins > Scripting > Open Source for Menu Item.
    • Run the command whose source you want to see.
      • E.g., Process > Binary > Make Binary.
    • This will open the source using the gitweb interface.


What are "external" plugins?


Where to put the jars of my plugin?


How can I call ImageJ from my software?



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





  • Every time you need to update the version of ImageJ, you must redeploy the entire uber-JAR (~57 MB as of June 2014). If you bundle individual JAR components, you need only update those that changed. This issue is of particular relevant to Java applications deployed via Java Web Start, since it automatically downloads the latest available version of each JAR dependency; in that case, your application startup time will suffer if you use the uber-JAR.
  • If you rely on any of the same dependencies that ImageJ does, you may run into trouble (e.g., NoSuchMethodError) with multiple copies of those dependencies on your classpath, especially if you need to use a different version of that dependency than is bundled with the uber-JAR.





See also:




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




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


The Wiki is lacking documentation about X, Y and Z


How do I find more information about Command X?



  1. Open the Command Finder (Shortcut: L)
  2. Filter to the command you're interested in.


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


How to report issues?




There are only three professional developers (User:Rueden, User:Hinerm and User:Schindelin) whose formal jobs include responding to and addressing bug reports. None of them are 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, SLIM Curve, Git for Windows and msysGit, NAR plugin for Maven, and others.




See the bug reporting best practices article for details.


See the Contributing page!



See the Philosophy page!



Why does ImageJ still target Java 6?



See this mailing list thread for further details.


See the Philosophy page!





Why is open software vital to science?

See the Open Source page!