imagecodecs 2026.1.14

Image transformation, compression, and decompression codecs

Imagecodecs is a Python library that provides block-oriented, in-memory buffer transformation, compression, and decompression functions for use in tifffile, liffile, czifile, zarr, and other scientific image input/output packages.

Decode and/or encode functions are implemented for Zlib (DEFLATE), GZIP, LZMA, ZStandard (ZSTD), Blosc, Brotli, Snappy, BZ2, LZ4, LZ4F, LZ4HC, LZ4H5, LZW, LZO, LZF, LZFSE, LZHAM, PGLZ (PostgreSQL LZ), RCOMP (Rice), ZFP, SZ3, Meshopt, Pcodec, SPERR, AEC, SZIP, LERC, EER, NPY, BCn, DDS, BMP, PNG, APNG, GIF, TIFF, WebP, JPEG (2 to 16-bit), Lossless JPEG (LJPEG, LJ92, JPEGLL), JPEG 2000 (JP2, J2K), High-throughput JPEG 2000 (HTJ2K, JPH), JPEG LS, JPEG XL, JPEG XS, JPEG XR (WDP, HD Photo), Ultra HDR (JPEG_R), MOZJPEG, AVIF, HEIF, QOI, RGBE (HDR), Jetraw, DICOM RLE, PackBits, Packed Integers, Delta, XOR Delta, Floating Point Predictor, Bitorder reversal, Byteshuffle, Bitshuffle, Float24 (24-bit floating point), Bfloat16 (brain floating point), Quantize (Scale, BitGroom, BitRound, GranularBR), and CMS (color space transformations). Checksum functions are implemented for CRC-32, Adler-32, Fletcher-32, and Jenkins lookup3.

Author:

Christoph Gohlke

License:

BSD-3-Clause

Version:

2026.1.14

DOI:

10.5281/zenodo.6915978

Quickstart

Install the imagecodecs package and all dependencies from the Python Package Index:

python -m pip install -U "imagecodecs[all]"

Imagecodecs is also available in other package repositories such as Anaconda, MSYS2, and MacPorts.

See Requirements and Notes for building from source.

See Examples for using the programming interface.

Source code and support are available on GitHub.

Requirements

This revision was tested with the following requirements and dependencies (other versions may work):

• CPython 3.11.9, 3.12.10, 3.13.11, 3.14.2 64-bit

• numpy 2.4.1

• numcodecs 0.16.5 (optional, for Zarr file format 2 compatible codecs)

Build requirements:

• cython 3.2.4

• brotli 1.2.0

• bzip2 1.0.8

• c-blosc 1.21.6

• c-blosc2 2.22.0

• charls 2.4.2

• giflib 5.2.2

• jxrlib 1.2

• lcms2 2.18

• lerc 4.0.4

• libaec 1.1.4

• libavif 1.3.0 (aom 3.13.1, dav1d 1.5.3, rav1e 0.8.1, svt-av1 3.1.2, libyuv main, libxml2 2.15.1)

• libdeflate 1.25

• libheif 1.21.1 (libde265 1.0.16, x265 4.1)

• libjpeg-turbo 3.1.3

• libjxl 0.11.1

• libjxs 2.0.2

• liblzma 5.8.2

• libpng 1.6.53

• libpng-apng 1.6.53

• libtiff 4.7.1

• libultrahdr 1.4.0

• libwebp 1.6.0

• lz4 1.10.0

• meshoptimizer 1.0

• openjpeg 2.5.4

• openjph 0.26.0

• pcodec 0.4.9 (unstable)

• snappy 1.2.2

• sperr 0.8.4

• sz3 3.3.2

• zfp 1.0.1

• zlib 1.3.1.2

• zlib-ng 2.3.2

• zstd 1.5.7

Unmaintained or discontinued build requirements:

• brunsli 0.1

• jetraw 23.03.16.4

• lzfse 1.0

• lzham_codec 1.0

• lzokay db2df1f

• mozjpeg 4.1.5

• zopfli 1.0.3

Vendored requirements:

• bcdec.h 93628fe

• bitshuffle 0.5.2

• cfitsio ricecomp.c modified

• h5checksum.c modified

• jpg_0XC3.cpp modified

• liblj92 modified

• liblzf 3.6

• libspng 0.7.4

• nc4var.c modified

• pg_lzcompress.c modified

• qoi.h 4461cc3

• rgbe.c modified

Test requirements:

• tifffile 2025.12.20

• czifile 2019.7.2.1

• liffile 2025.12.12

• zarr 3.1.5

• python-blosc 1.11.3

• python-blosc2 3.11.2

• python-brotli 1.2.0

• python-lz4 4.4.5

• python-lzf 0.2.6

• python-snappy 0.7.3

• pyliblzfse 0.4.1

• backports.zstd 1.3.0

• zopflipy 1.12

Revisions

2026.1.14

• Pass 8281 tests.

• Add tiff_encode function.

• Add extra options for HTJ2K (#134).

• Add linear RGB option to cms_profile.

• Change ZSTD default compression level to 3.

2026.1.1

• Enforce positional-only and keyword-only parameters (breaking).

• Base numcodecs.Jpeg on JPEG8 codec (breaking).

• Add HTJ2K codec based on OpenJPH library (#125).

• Add MESHOPT codec based on meshoptimizer library.

• Fix decoding concatenated ZStandard frames.

• Fix potential issues in TIFF and WEBP codecs.

• Fix pyi stub file.

• Change default Brotli compression level to 4.

• Use Brotli streaming API for decoding.

• Enable decoding UltraHDR to uint16.

• Tweak memory allocation and reallocation strategies.

• Use fused types.

• Improve code quality.

2025.11.11

• Fix EER superresolution decoding (breaking; see tifffile #313).

• Add option to eer_decode to add to uint16 array.

• Add option to specify CICP/NCLX parameters in avif_encode (#131).

• Add BFLOAT16 codec.

• Build ABI3 wheels.

• Require Cython >= 3.2.

• Deprecate Python 3.11.

2025.8.2

• Fix szip_encode default output buffer might be too small (#128).

• Fix minor bugs in LZ4H5 codec (#127).

• Avoid grayscale-to-RGB conversions in AVIF codecs.

• Improve AVIF error messages.

• Add flag for free-threading compatibility (#113).

• Do not use zlib uncompress2, which is not available on manylinux.

• Do not build unstable BRUNSLI, PCODEC, SPERR, and SZ3 codecs.

• Require libavif >= 1.3 and Cython >= 3.1.

• Support Python 3.14 and 3.14t.

• Drop support for Python 3.10 and PyPy.

2025.3.30

• Fix some codecs for use with Zarr 3, zarr_format=2 (#123).

• Fix LZ4H5 codec when block size is less than compressed size (#126).

• Fix pglz_compress is not thread-safe.

• Set __module__ attribute on public objects.

• Drop support for Python 3.9, deprecate Python 3.10.

2024.12.30

• …

Refer to the CHANGES file for older revisions.

Objectives

Many scientific image storage formats, such as TIFF, CZI, XLIF, DICOM, HDF, and Zarr are containers that store numerous small data segments (chunks, tiles, stripes). These segments are encoded using various compression and pre-filtering methods. Metadata common to all data segments are typically stored separately from the segments.

The purpose of the Imagecodecs library is to support Python modules in encoding and decoding such data segments. The specific aims are:

• Provide functions for encoding and decoding small image data segments in-memory (as opposed to in-file) from and to bytes or numpy arrays for many compression and filtering methods.

• Support image formats and compression methods that are not available elsewhere in the Python ecosystem.

• Reduce the runtime dependency on numerous, large, inapt, or unmaintained Python packages. The Imagecodecs package only depends on numpy.

• Implement codecs as Cython wrappers of third-party libraries with a C API and permissive license if available; otherwise use own C library. Provide Cython definition files for the wrapped C libraries.

• Release the Python global interpreter lock (GIL) during extended native/C function calls for multi-threaded use.

Accessing parts of large data segments and reading metadata from segments are outside the scope of this library.

Notes

This library is largely a work in progress.

The API is not stable yet and might change between revisions.

Python <= 3.10 is no longer supported. 32-bit versions are deprecated.

Works on little-endian platforms only.

Supported platforms are win_amd64, win_arm64, win32, macosx_x86_64, macosx_arm64, manylinux_x86_64, and manylinux_aarch64.

Wheels may not be available for all platforms and all releases.

Not all features are available on all platforms.

The bcn, dds, dicomrle, eer, lzo, packints, and jpegsof3 codecs are currently decode-only.

The brunsli and pcodec codecs are distributed as source code only because the underlying libraries are unstable.

The heif, jetraw, and jpegxs codecs are distributed as source code only due to license and possible patent usage issues.

The latest Microsoft Visual C++ Redistributable for Visual Studio 2017-2026 is required on Windows.

Refer to the imagecodecs/licenses folder for 3rd-party library licenses.

This software is based in part on the work of the Independent JPEG Group.

Update pip and setuptools to the latest version before installing imagecodecs:

python -m pip install -U pip setuptools wheel Cython.

When building against libjpeg or libjpeg_turbo < 3, set the environment variable IMAGECODECS_JPEG8_LEGACY=1 to enable legacy API support.

Before building imagecodecs from source code, install required tools and libraries. For example, on latest Ubuntu Linux distributions:

sudo apt-get install build-essential python3-dev cython3 python3-pip python3-setuptools python3-wheel python3-numpy libdeflate-dev libjpeg-dev libjxr-dev liblcms2-dev liblz4-dev liblerc-dev liblzma-dev libopenjp2-7-dev libpng-dev libtiff-dev libwebp-dev libz-dev libzstd-dev

To build and install imagecodecs from source code, run:

python -m pip install .

Many extensions are disabled by default when building from source.

To define which extensions are built, or to modify build settings such as library names and compiler arguments, provide a imagecodecs_distributor_setup.customize_build function, which is imported and executed during setup. See setup.py for pre-defined customize_build functions.

Other projects providing imaging or compression codecs: stdlib-zlib, stdlib-bz2, stdlib-lzma, backports.lzma, python-lzo, python-lzw, python-lerc, wavpack-numcodecs, packbits, isa-l.igzip, fpzip, libmng, openexr, openzl, openhtj2k, pyjetraw, tinyexr, pytinyexr, pyroexr, jasper, libjpeg (gpl), pylibjpeg, pylibjpeg-libjpeg (gpl), pylibjpeg-openjpeg, pylibjpeg-rle, glymur, pyheif, pyrus-cramjam, pylzham, brieflz, quicklz (gpl), lzo (gpl), nvjpeg, nvjpeg2k, pyturbojpeg, ccsds123, lpc-rice, compression-algorithms, compressonator, wuffs, tinydng, grok (agpl), mafisc, b3d, fo-dicom.codecs, jpegli, hdf5plugin.

Examples

Import the JPEG2K codec:

>>> from imagecodecs import (
...     jpeg2k_encode,
...     jpeg2k_decode,
...     jpeg2k_check,
...     jpeg2k_version,
...     JPEG2K,
... )

Check that the JPEG2K codec is available in the imagecodecs build:

>>> JPEG2K.available
True

Print the version of the JPEG2K codec’s underlying OpenJPEG library:

>>> jpeg2k_version()
'openjpeg 2.5.4'

Encode a numpy array in lossless JP2 format:

>>> import numpy
>>> array = numpy.random.randint(100, 200, (256, 256, 3), numpy.uint8)
>>> encoded = jpeg2k_encode(array, level=0)
>>> bytes(encoded[:12])
b'\x00\x00\x00\x0cjP  \r\n\x87\n'

Check that the encoded bytes likely contain a JPEG 2000 stream:

>>> jpeg2k_check(encoded)
True

Decode the JP2 encoded bytes to a numpy array:

>>> decoded = jpeg2k_decode(encoded)
>>> numpy.array_equal(decoded, array)
True

Decode the JP2 encoded bytes to an existing numpy array:

>>> out = numpy.empty_like(array)
>>> _ = jpeg2k_decode(encoded, out=out)
>>> numpy.array_equal(out, array)
True

Not all codecs are fully implemented, raising exceptions at runtime:

>>> from imagecodecs import packints_encode
>>> packints_encode(array, 8)
Traceback (most recent call last):
 ...
NotImplementedError: packints_encode

Write the numpy array to a JP2 file:

>>> from imagecodecs import imwrite, imread
>>> imwrite('_test.jp2', array)

Read the image from the JP2 file as numpy array:

>>> image = imread('_test.jp2')
>>> numpy.array_equal(image, array)
True

Create a JPEG 2000 compressed Zarr array:

>>> import zarr
>>> import numcodecs
>>> from imagecodecs.numcodecs import Jpeg2k
>>> numcodecs.register_codec(Jpeg2k)
>>> zarr.zeros(
...     (4, 5, 512, 512, 3),
...     chunks=(1, 1, 256, 256, 3),
...     dtype='u1',
...     compressor=Jpeg2k(),
...     zarr_format=2,
... )
<...Array ...(4, 5, 512, 512, 3) ...uint8>

Access image data in a sequence of JP2 files via tifffile.FileSequence and dask.array:

>>> import tifffile
>>> import dask.array
>>> def jp2_read(filename):
...     with open(filename, 'rb') as fh:
...         data = fh.read()
...     return jpeg2k_decode(data)
...
>>> with tifffile.FileSequence(jp2_read, '*.jp2') as ims:
...     with ims.aszarr() as store:
...         dask.array.from_zarr(store)
...
dask.array<from-zarr, shape=(1, 256, 256, 3)...chunksize=(1, 256, 256, 3)...

Write the Zarr store to a fsspec ReferenceFileSystem in JSON format and open it as a Zarr array:

>>> store.write_fsspec(
...     'temp.json', url='file://', codec_id='imagecodecs_jpeg2k'
... )
>>> from kerchunk.utils import refs_as_store
>>> zarr.open(refs_as_store('temp.json'), mode='r')
<Array <FsspecStore(ReferenceFileSystem, /)> shape=(1, 256, 256, 3) dtype=uint8>

View the image in the JP2 file from the command line:

python -m imagecodecs _test.jp2