Command line tools

There are several scripts for using Bio-Formats on the command line.


Download, unzip it into a new folder.


As of Bio-Formats 5.0.0, this zip now contains the bundled jar and you no longer need to download loci_tools.jar or the new bioformats_package.jar separately.

The zip file contains both Unix scripts and Windows batch files.

Tools available

Currently available tools include:

Prints information about a given image file to the console, and displays the image itself in the Bio-Formats image viewer (see Displaying images and metadata for more information).
Displays the given image file in ImageJ using the Bio-Formats Importer plugin. See Display file in ImageJ for details.
Converts an image file from one format to another. Bio-Formats must support writing to the output file (see Converting a file to different format for more information).
Displays a list of supported file formats in HTML, plaintext or XML. See List supported file formats for details.
A simple XML prettifier similar to xmllint --format but more robust in that it attempts to produce output regardless of syntax errors in the XML. See Format XML data for details.
A command-line XML validation tool, useful for checking an OME-XML document for compliance with the OME-XML schema. See Validating XML in an OME-TIFF for details.
Dumps the comment from the given TIFF file’s first IFD entry; useful for examining the OME-XML block in an OME-TIFF file (also see Editing XML in an OME-TIFF).
Displays a list of imaging domains and the supported formats associated with each domain. See List formats by domain for more information.
Creates a “fake” high-content screen with configurable dimensions. This is useful for testing how HCS metadata is handled, without requiring real image data from an acquired screen. See Create a high-content screen for testing for more information.

Some of these tools also work in combination, for example Validating XML in an OME-TIFF uses both tiffcomment and xmlvalid.

Running any of these commands without any arguments will print usage information to help you. When run with the -version argument, showinf and bfconvert will display the version of Bio-Formats that is being used (version number, build date, and Git commit reference).

Command-line environment

A set of environment variables can be passed to all command-line utilities:

Extra directories to be added to the autodetected command-line classpath e.g. for external reader JARs. Default: empty.
Additional flags to be sent to the JVM. Default: empty.
Maximum heap size to be allocated to the JVM. Default: 512m.
Enable profiling - see Profiling for more information. Default: off.
Maximum profiling depth if profiling is activated. Default: 30.

Using the tools directly from source

Firstly, obtain a copy of the sources and build them (see Obtaining and building Bio-Formats). You can configure the scripts to use your source tree instead of bioformats_package.jar in the same directory by following these steps:

  1. Point your CLASSPATH to the checked-out directory and the JAR files in the jar folder.
    • E.g. on Windows with Java 1.8 or later, if you have checked out the source at C:\code\bio-formats, set your CLASSPATH environment variable to the value C:\code\bio-formats\jar\*;C:\code\bio-formats. You can access the environment variable configuration area by right-clicking on My Computer, choosing Properties, Advanced tab, Environment Variables button.
  2. Compile the source with ant compile.
  3. Set the BF_DEVEL environment variable to any value (the variable just needs to be defined).

Version checker

If you run bftools outside of the OMERO environment, you may encounter an issue with the automatic version checker causing a tool to crash when trying to connect to The error message will look something like this:

Failed to compare version numbers Server returned HTTP response code: 400 for URL:;;os.

To avoid this issue, call the tool with the -no-upgrade parameter.


For debugging errors or investigating performance issues, it can be useful to use profiling tools while running Bio-Formats. The command-line tools can invoke the HPROF agent library to profile Heap and CPU usage. Setting the BF_PROFILE environment variable allows to turn profiling on, e.g.:

BF_PROFILE=true showinf -nopix -no-upgrade myfile