JPEG XL reference implementation

Build&Test
Releases
Doc
codecov

JXL logo

This repository contains a reference implementation of JPEG XL (encoder and
decoder), called libjxl. This software library is
used by many applications that support JPEG XL.

JPEG XL is in the final stages of standardization and its codestream and file format
are frozen.

The library API, command line options, and tools in this repository are subject
to change, however files encoded with cjxl conform to the JPEG XL format
specification and can be decoded with current and future djxl decoders or
libjxl decoding library.

Quick start guide

For more details and other workflows see the “Advanced guide” below.

Checking out the code

git clone https://github.com/libjxl/libjxl.git --recursive --shallow-submodules

This repository uses git submodules to handle some third party dependencies
under third_party, that’s why is important to pass --recursive. If you
didn’t check out with --recursive, or any submodule has changed, run:

git submodule update --init --recursive --depth 1 --recommend-shallow

The --shallow-submodules and --depth 1 --recommend-shallow options create
shallow clones which only downloads the commits requested, and is all that is
needed to build libjxl. Should full clones be necessary, you could always run:

git submodule foreach git fetch --unshallow
git submodule update --init --recursive

which pulls the rest of the commits in the submodules.

Important: If you downloaded a zip file or tarball from the web interface you
won’t get the needed submodules and the code will not compile. You can download
these external dependencies from source running ./deps.sh. The git workflow
described above is recommended instead.

Installing dependencies

Required dependencies for compiling the code, in a Debian/Ubuntu based
distribution run:

sudo apt install cmake pkg-config libbrotli-dev libgflags-dev

Optional dependencies for supporting other formats in the cjxl/djxl tools,
in a Debian/Ubuntu based distribution run:

sudo apt install libgif-dev libjpeg-dev libopenexr-dev libpng-dev libwebp-dev

We recommend using a recent Clang compiler (version 7 or newer), for that
install clang and set CC and CXX variables.

sudo apt install clang
export CC=clang CXX=clang++

Building

cd libjxl
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=OFF ..
cmake --build . -- -j$(nproc)

The encoder/decoder tools will be available in the build/tools directory.

Installing

sudo cmake --install .

Basic encoder/decoder

To encode a source image to JPEG XL with default settings:

build/tools/cjxl input.png output.jxl

For more settings run build/tools/cjxl --help or for a full list of options
run build/tools/cjxl -v -v --help.

To decode a JPEG XL file run:

build/tools/djxl input.jxl output.png

When possible cjxl/djxl are able to read/write the following
image formats: .exr, .gif, .jpeg/.jpg, .pfm, .pgm/.ppm, .pgx, .png.

Benchmarking

For speed benchmarks on single images in single or multi-threaded decoding
djxl can print decoding speed information. See djxl --help for details
on the decoding options and note that the output image is optional for
benchmarking purposes.

For more comprehensive benchmarking options, see the
benchmarking guide.

Advanced guide

Building with Docker

We build a common environment based on Debian/Ubuntu using Docker. Other
systems may have different combinations of versions and dependencies that
have not been tested and may not work. For those cases we recommend using the
Docker container as explained in the
step by step guide.

Building JPEG XL for developers

For experienced developers, we provide build instructions for several other environments:

If you encounter any difficulties, please use Docker instead.

License

This software is available under a 3-clause BSD license which can be found in
the LICENSE file, with an “Additional IP Rights Grant” as outlined in
the PATENTS file.

Please note that the PATENTS file only mentions Google since Google is the legal
entity receiving the Contributor License Agreements (CLA) from all contributors
to the JPEG XL Project, including the initial main contributors to the JPEG XL
format: Cloudinary and Google.

Additional documentation

Codec description

Development process

Contact

If you encounter a bug or other issue with the software, please open an Issue here.

There is a subreddit about JPEG XL, and
informal chatting with developers and early adopters of libjxl can be done on the
JPEG XL Discord server.

GitHub

View Github