.. This file is generated by setup.py

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), PixarLog, Jetraw, DICOM RLE, CCITT (RLE, T.4 and T.6), PackBits, Packed Integers (TIFF, MONO p and packed), 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 <https://www.cgohlke.com>_ :License: BSD-3-Clause :Version: 2026.3.6 :DOI: 10.5281/zenodo.6915978 <https://doi.org/10.5281/zenodo.6915978>_

Quickstart

Install the imagecodecs package and all dependencies from the Python Package Index <https://pypi.org/project/imagecodecs/>_::

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

Imagecodecs is also available in other package repositories such as Anaconda <https://anaconda.org/conda-forge/imagecodecs>, MSYS2 <https://packages.msys2.org/base/mingw-w64-python-imagecodecs>, and MacPorts <https://ports.macports.org/port/py-imagecodecs/summary>_.

See Requirements_ and Notes_ for building from source.

See Examples_ for using the programming interface.

Source code and support are available on GitHub <https://github.com/cgohlke/imagecodecs>_.

Requirements

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

• CPython <https://www.python.org>_ 3.11.9, 3.12.10, 3.13.12, 3.14.3 64-bit
• numpy <https://pypi.org/project/numpy>_ 2.4.2
• numcodecs <https://pypi.org/project/numcodecs/>_ 0.16.5 (optional, for Zarr file format 2 compatible codecs)

Build requirements:

• cython <https://github.com/cython/cython>_ 3.2.4
• brotli <https://github.com/google/brotli>_ 1.2.0
• bzip2 <https://gitlab.com/bzip2/bzip2>_ 1.0.8
• c-blosc <https://github.com/Blosc/c-blosc>_ 1.21.6
• c-blosc2 <https://github.com/Blosc/c-blosc2>_ 2.23.0
• charls <https://github.com/team-charls/charls>_ 2.4.3
• giflib <https://sourceforge.net/projects/giflib/>_ 6.1.1
• jxrlib <https://github.com/cgohlke/jxrlib>_ 1.2
• lcms2 <https://github.com/mm2/Little-CMS>_ 2.18
• lerc <https://github.com/Esri/lerc>_ 4.0.4
• libaec <https://gitlab.dkrz.de/k202009/libaec>_ 1.1.6
• libavif <https://github.com/AOMediaCodec/libavif>_ 1.4.0 (aom <https://aomedia.googlesource.com/aom>_ 3.13.1, dav1d <https://github.com/videolan/dav1d>_ 1.5.3, rav1e <https://github.com/xiph/rav1e>_ 0.8.1, svt-av1 <https://gitlab.com/AOMediaCodec/SVT-AV1>_ 4.0.1, libyuv <https://chromium.googlesource.com/libyuv/libyuv>_ main, libxml2 <https://gitlab.gnome.org/GNOME/libxml2>_ 2.15.2)
• libdeflate <https://github.com/ebiggers/libdeflate>_ 1.25
• libheif <https://github.com/strukturag/libheif>_ 1.21.2 (libde265 <https://github.com/strukturag/libde265>_ 1.0.16, x265 <https://bitbucket.org/multicoreware/x265_git/src/master/>_ 4.1)
• libjpeg-turbo <https://github.com/libjpeg-turbo/libjpeg-turbo>_ 3.1.3
• libjxl <https://github.com/libjxl/libjxl>_ 0.11.2
• libjxs <https://jpeg.org/jpegxs/software.html>_ 2.0.2
• liblzma <https://github.com/tukaani-project/xz>_ 5.8.2
• libpng <https://github.com/glennrp/libpng>_ 1.6.55
• libpng-apng <https://sourceforge.net/projects/libpng-apng/>_ 1.6.55
• libtiff <https://gitlab.com/libtiff/libtiff>_ 4.7.1 (with issue 789 fix)
• libultrahdr <https://github.com/google/libultrahdr>_ 1.4.0
• libwebp <https://github.com/webmproject/libwebp>_ 1.6.0
• lz4 <https://github.com/lz4/lz4>_ 1.10.0
• meshoptimizer <https://github.com/zeux/meshoptimizer>_ 1.0.1
• openjpeg <https://github.com/uclouvain/openjpeg>_ 2.5.4
• openjph <https://github.com/aous72/OpenJPH>_ 0.26.3
• pcodec <https://github.com/mwlon/pcodec>_ 1.0.1 (with PR 369)
• snappy <https://github.com/google/snappy>_ 1.2.2
• sperr <https://github.com/NCAR/SPERR>_ 0.8.4
• sz3 <https://github.com/szcompressor/SZ3>_ 3.3.2
• zfp <https://github.com/LLNL/zfp>_ 1.0.1
• zlib <https://github.com/madler/zlib>_ 1.3.2
• zlib-ng <https://github.com/zlib-ng/zlib-ng>_ 2.3.3
• zstd <https://github.com/facebook/zstd>_ 1.5.7

Unmaintained or discontinued build requirements:

• brunsli <https://github.com/google/brunsli>_ 0.1
• jetraw <https://github.com/Jetraw>_ 23.03.16.4
• lzfse <https://github.com/lzfse/lzfse/>_ 1.0
• lzham_codec <https://github.com/richgel999/lzham_codec/>_ 1.0
• lzokay <https://github.com/AxioDL/lzokay>_ db2df1f
• mozjpeg <https://github.com/mozilla/mozjpeg>_ 4.1.5
• zopfli <https://github.com/google/zopfli>_ 1.0.3

Vendored requirements:

• bcdec.h <https://github.com/iOrange/bcdec>_ 93628fe
• bitshuffle <https://github.com/kiyo-masui/bitshuffle>_ 0.5.2
• cfitsio ricecomp.c <https://heasarc.gsfc.nasa.gov/fitsio/>_ modified
• h5checksum.c <https://github.com/HDFGroup/hdf5/>_ modified
• jpg_0XC3.cpp <https://github.com/rordenlab/dcm2niix/blob/master/console/jpg_0XC3.cpp>_ modified
• liblj92 <https://bitbucket.org/baldand/mlrawviewer/src/master/liblj92/>_ modified
• liblzf <http://oldhome.schmorp.de/marc/liblzf.html>_ 3.6
• libspng <https://github.com/randy408/libspng>_ 0.7.4
• nc4var.c <https://github.com/Unidata/netcdf-c/blob/main/libsrc4/nc4var.c>_ modified
• pg_lzcompress.c <https://github.com/postgres/postgres>_ modified
• qoi.h <https://github.com/phoboslab/qoi/>_ 4461cc3
• rgbe.c <https://www.graphics.cornell.edu/~bjw/rgbe/rgbe.c>_ modified

Test requirements:

• tifffile <https://github.com/cgohlke/tifffile>_ 2026.3.3
• czifile <https://github.com/cgohlke/czifile>_ 2019.7.2.3
• liffile <https://github.com/cgohlke/liffile>_ 2026.2.16
• zarr <https://github.com/zarr-developers/zarr-python>_ 3.1.5
• python-blosc <https://github.com/Blosc/python-blosc>_ 1.11.4
• python-blosc2 <https://github.com/Blosc/python-blosc2>_ 4.0.0
• python-brotli <https://github.com/google/brotli/tree/master/python>_ 1.2.0
• python-lz4 <https://github.com/python-lz4/python-lz4>_ 4.4.5
• python-lzf <https://github.com/teepark/python-lzf>_ 0.2.6
• python-snappy <https://github.com/andrix/python-snappy>_ 0.7.3
• pyliblzfse <https://github.com/ydkhatri/pyliblzfse>_ 0.4.1
• backports.zstd <https://github.com/rogdham/backports.zstd>_ 1.3.0
• zopflipy <https://github.com/hattya/zopflipy>_ 1.12

Revisions

2026.3.6

• Pass 8575 tests.
• Add CCITTRLE, CCITTFAX3 and CCITTFAX4 codecs (decode only).
• Implement packints_encode function.
• Support lerc subcodec in tiff_encode function.
• Support packed integers, ccitt and pixarlog compression in TIFF codec.
• Support bitorder option in PACKINTS codec.
• Support rounding in BFLOAT16 codec.
• Support more BMP types.
• Update PCODEC to new API.
• Fix buffer overflows in third-party code.
• Fix code review issues.

2026.1.14

• 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