JPEG2000, Java and PDF

The Background

The JPEG 2000 compression algorithm was designed in 2000 as a successor to the venerable JPEG algorithm, which dates back to 1992. It's designed to compress "continuous tone" images such as photographs, and supports both a lossy (like JPEG) and a lossless format. We covered a bit on image compression in a previous article.

Adobe added support for JPEG 2000 compressed images in Acrobat 5.0, (calling it JPX compression), and it's becoming more and more common to find PDF Documents containing photographic images compressed with this algorithm.

The Problem

Java supports JPEG 2000, but this capability is not included with the JDK by default. This only becomes a problem when you try to display (or convert to bitmap) a PDF containing a JPEG 2000 compressed image: if support isn't available, you'll see the Exception:

 PDF WARNING SP2: Unable to create image: caused by No JPEG2000 decoding support in ImageIO package

The image in question will be a gray square instead

The Solution (Updated for 2016)

The original version of this article from 2009 referred to some links which have long since disappeared from the web. If you have the Jars from that era, they will still work, but if not then a version of the code still exists. As best as we can tell it is functionally equivalent to the original release, so there is no point in moving from one to the other: if you have a working solution with the original Jars, don't change anything.

The current resting place for the code is in these two Github repositories: the core files and the JPEG2000 files. The class hierarchy is slightly different to the original codebase, but our API will handle either.

If you're familiar with Github and Maven then building from source is probably the easiest route. You will need the following two Jars in your classpath:

  • jai-imageio-core-NNN.jar, from the jai-imageio-core package. At the time of writing you can download a pre-built binary directly from Bintray.
  • jai-imageio-jpeg2000-NNN.jar, from the jai-imageio-jpeg2000 package. At the time of writing you can download a pre-build binary direcly from Bintray

The addition of those two Jars to your classpath will allow the PDF library to decode JPEG2000-encoded data in PDF files.

The content below is no longer valid, but it remains for posterity

The Solution

The fix is to install the Java Advanced Imaging API. This is available for Windows, Linux and Solaris - there's licensing and a lot more information at that site and we'd recommend looking around, but as this is a quick and dirty installation guide we'll cut directly to the chase.


  1. Open
  2. Download the "tar.gz" file of the latest daily build for your architecture - we recommend the daily releases, as the stable 1.1 release doesn't work with some of the JPEG2000 streams you're likely to find in PDF
  3. Untar the file.
  4. Copy the contents of jai_imageio-1_2-nnn/lib to the $JAVA_HOME/jre/lib/ext folder of your JDK.

Linux typically installs Java in /usr/lib/jvm/version, where version depends on which JDK you installed. Here's what I typed:

unzip jai_imageio-1_2-lib-*.zip
cp -r lib /usr/lib/jvm/java-6-sun/jre

For Windows

  1. Open
  2. Download the latest daily release from the 1.2 series and unzip it. You'll have a bin and lib folder - the contents of these have to be copied to the bin and lib folders of your JDK install (typically something like C:\Program Files\Java\jre6.

If you're running the PDF Library in a web server you will need to restart it, but otherwise that's all that's required to add JPEG 2000 support to Java.