ImageJ: a public domain Java toolkit for measuring scientific images

What ImageJ actually solves for a lab

ImageJ exists to turn pixels into numbers. The README describes it in one line as public domain software for processing and analyzing scientific images, and the repository layout backs that up: there is an ij/ directory holding the Java source, a macros/ directory, a plugins/ directory, and a tests/ directory. That structure tells you the intended workflow. You load an image, run a measurement or a filter, and either read the result or extend the program with a macro or a plugin.

The audience is narrow and specific. It is people who need reproducible measurements from microscopy, gels, blots or similar instrument output, and who are willing to work either in the GUI or through Java and macro code. It is not a general photo editor and it is not a computer vision framework in the modern sense, despite the computer-vision topic tag on the repository. The unit of work is a calibrated scientific image, not a photograph.

Because it is written in Java, the README notes it runs on many different platforms. That portability is the practical reason the project has survived so long. A measurement routine written once can be handed to a collaborator on a different operating system without a rewrite.

How ImageJ is put together: Java source, macros, plugins

The architecture visible in the repository is a single Java application with two extension surfaces. The first is macros, held in the macros/ directory. The second is plugins, held in plugins/. Both are loaded by the core in ij/. The presence of IJ_Props.txt at the top level is consistent with the classic ImageJ pattern of a properties file that supplies strings and configuration to the running application.

There is also a module-info.java at the top level, which means the codebase carries a Java module descriptor in addition to the older Ant build file, build.xml, and the Maven pom.xml. Three build descriptions in one repository is a sign of a project that has accumulated packaging conventions over a long life rather than one designed around a single toolchain. The README confirms this impression by documenting both Ant and Maven paths side by side.

The Maven coordinates are the clearest statement of how the code is meant to be consumed by other software: groupId net.imagej, artifactId ij. That is the artifact you depend on if you want ImageJ as a library rather than as an end-user program. Everything else in the repository, including applet.html and run_appletviewer.bat, reflects an era when running analysis in a browser was a realistic target. Those files are still present but the README does not present them as a current usage path.

Adding ImageJ as a Maven dependency

The README gives the dependency block directly. The version shown is 1.53j, and the README notes that versions from 1.48r onward are on Maven Central while versions up to 1.48q live in the SciJava Maven repository. It also warns that versions before 1.53k may not identically match the corresponding release tags in this repository, which is the kind of caveat worth reading twice before you pin an old version for reproducibility.

<dependency>
  <groupId>net.imagej</groupId>
  <artifactId>ij</artifactId>
  <version>1.53j</version>
</dependency>

After adding that to your pom.xml and resolving dependencies, the artifact should appear in your local repository and you can import ImageJ classes in your own Java code. The README does not list the class names or entry points, so the next step is the project Javadoc, which the build can generate for you.

If you would rather not guess at the API, generate the documentation locally. The README documents this Maven goal, and the output lands in target/apidocs.

mvn javadoc:javadoc

That directory is where to look for the classes you would call from a plugin or a batch script.

Building from source and the JDK ceiling

This is where ImageJ shows its age most plainly. The README recommends building with OpenJDK 8 or 11 and states that building with newer versions, naming 17, 21 and 25, is not currently supported. The stated reason is that ImageJ bytecode targets Java 1.6 as the minimum Java version. That single constraint shapes everything downstream: your CI image, your developer machines, and any other library you want to link against in the same build.

With Maven, the README gives three commands. Plain mvn compiles and packages ImageJ into a JAR in the target directory. The exec profile compiles and then runs the program. The javadoc goal produces documentation.

mvn
mvn -Pexec
mvn javadoc:javadoc

The first produces the JAR, the second launches ImageJ from source, and the third writes Javadoc into target/apidocs. If you prefer Ant, the README points at build.xml in the repository root and links to a bundled Ant distribution at imagej.nih.gov that is set up to use the JVM shipped with the Windows version of ImageJ. That link is a strong hint about the primary historical deployment target. A team on a modern Linux toolchain will find the Maven route less surprising, but it still has to hold the JDK at 8 or 11.

Where ImageJ is the wrong tool

The JDK restriction is not a cosmetic problem. If your organisation has standardised on JDK 17 or later, ImageJ as a source build sits outside that standard, and the README offers no statement about when or whether that will change. You can still consume the published artifact, but you cannot assume the source tree will compile in the same environment as the rest of your code.

Packaging is the second weak point. The repository contains build.xml, pom.xml and module-info.java, and the README documents Ant and Maven but not a reproducible release process, a versioning policy, or a rollback path. No releases were retrieved for this page, so there is nothing here to tell you how frequently artifacts appear on Maven Central or how a regression would be reverted. Any team that needs a documented upgrade and downgrade procedure is working without documentation.

Licensing is the third area to check rather than assume. The README links to a public domain disclaimer, but the repository metadata reports the licence as NOASSERTION and the LICENSE.txt file is the authority. Public domain status in one jurisdiction is not automatically the same everywhere, and bundled third-party code can carry different terms. That is a question for your own counsel, not something the README settles.

Finally, ImageJ is the wrong choice when the work is interactive and exploratory rather than scripted. If your need is a maintained desktop application with a large bundled plugin collection, the README itself points you elsewhere.

ImageJ versus Fiji, and what the difference means in practice

The README treats Fiji as a separate project, linking to it from the wiki section, and lists it alongside ImageJ2 as a derivative or flavor. The distinction matters because the two answer different questions.

ImageJ, as this repository presents it, is the core. You get the Java source, the macro and plugin directories, the Ant and Maven builds, and the net.imagej:ij artifact. If you are embedding measurement logic in a larger Java system, or you want to control exactly which components are present, this is the layer you want. The trade-off is that you assemble your own environment.

Fiji is presented as a distribution built around ImageJ with a curated set of components. Choosing it means accepting someone else's selection of plugins and update mechanism in exchange for not having to build that selection yourself. The README does not enumerate what Fiji adds, so the honest comparison is structural rather than feature-by-feature: core library and source versus packaged distribution. If your question is which plugins exist or how updates are delivered, this repository is silent and the ImageJ wiki is the place the README directs you.

Maintenance, upgrades and what the repository shows

The repository is not archived, and the last push was on 2026-07-22. That is recent enough that the codebase is being touched, but the README does not describe a release cadence, a support window for old versions, or a deprecation policy. The one concrete upgrade fact it does give is the version boundary: artifacts before 1.53k may not identically match the release tags in this repository. For anyone pinning a version to reproduce an analysis months later, that sentence is the most operationally important line in the document.

The upgrade cost is therefore mostly yours to manage. You pick a version, you record it, and you test. There is no migration guide in the README for moving between ImageJ versions, and no statement about which versions remain supported. The build constraint reinforces this: as long as the bytecode targets Java 1.6 and newer JDKs are unsupported for building, upgrading ImageJ is coupled to keeping an older JDK available somewhere in your environment.

On licensing, the README's own framing is public domain, with a link to the disclaimer page. The repository metadata does not assert a standard licence identifier. If you redistribute ImageJ inside a product, or bundle it with third-party plugins, read LICENSE.txt and the disclaimer rather than relying on the one-line description.

Editorial conclusion

Adopt ImageJ if you need a scriptable, public domain measurement engine you can embed in a Java pipeline or drive from macros, and if you can keep your build on OpenJDK 8 or 11. Do not adopt it if you expect a maintained modern desktop application with current JDK support, or if you need a documented upgrade path between releases, because the README documents neither. Before committing, verify the exact net.imagej:ij version you intend to pin, confirm it exists on Maven Central or the SciJava repository, and check that your toolchain compiles against a library whose bytecode targets Java 1.6.

Frequently asked questions

Official sources

1. imagej/ImageJ on GitHub
2. Issues
3. Project website
4. README