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 Programming interface and Examples for using the library.

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.12.10, 3.13.17, 3.14.10, 3.15.2 64-bit

• numpy 2.5.4

• zarr 3.4.2 (optional, for Zarr 3 compatible codecs)

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

Build requirements:

• Cython 3.3.1

• brotli 1.2.1

• bzip2 1.0.8

• c-blosc 1.21.7

• c-blosc2 3.6.0

• charls 2.4.5

• giflib 6.1.3

• isa-l 2.32.1

• jpegli main

• jxrlib 1.2

• lcms2 2.20.0

• lerc 4.3.0

• libaec 1.1.8

• libavif 1.4.2 (aom 3.15.3, dav1d 1.5.4, rav1e 0.8.1, svt-av1 4.3.0, libyuv main, libxml2 2.15.4)

• libdeflate 1.26

• libheif 1.23.7 (libde265 1.1.3, x265 4.2)

• libjpeg-turbo 3.2.1

• libjxl 0.12.0

• libjxs 3.0.2-ED3

• liblzma 5.8.4

• libpng 1.6.59

• libpng-apng 1.6.59

• libtiff 4.7.2 (with issue 864 patch)

• libultrahdr 2.0.2

• libwebp 1.6.0

• lz4 1.11.1

• meshoptimizer 1.3

• openexr 3.5.4 (imath 3.2.3)

• openjpeg 2.5.4

• openjph 0.33.0

• openzl 0.3.0

• pcodec 1.0.4

• snappy 1.3.1

• sperr 0.8.5

• sz3 3.4.0

• wavpack 5.9.0

• zfp 1.0.1

• zlib 1.4

• zlib-ng 2.3.3

• 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

Bundled source files:

• bcdec.h 80859ed

• bitshuffle 0.5.2

• bmp.c original 0BSD implementation

• ccitt.c original 0BSD implementation

• cfitsio ricecomp.c, pliocomp.c, hcompress.c modified

• h5checksum.c modified

• jpeg_tools.c original 0BSD implementation

• jpg_0XC3.cpp modified

• liblj92 modified

• liblzf 3.6

• libspng 0d37ad9

• nc4var.c modified

• pcx.c original 0BSD implementation

• pg_lzcompress.c modified

• libtiff pixarlog.c v4.7.1 modified

• qoi.h 4461cc3

• rgbe.c modified

• tga.c original 0BSD implementation

• wic.cpp original 0BSD implementation

Test requirements:

• tifffile 2026.11.8

• czifile 2026.11.8

• liffile 2026.11.8

• sdtfile 2026.11.6

• roifile 2026.11.6

• kerchunk 0.2.10

• python-blosc 1.11.4

• python-blosc2 4.14.1

• python-brotli 1.2.0

• python-lz4 4.4.5

• python-lzf 0.2.6

• python-snappy 0.6.1

• pyliblzfse 0.4.1

• backports.zstd 1.7.0

• zopflipy 1.13

Revisions

2026.11.11

• Rename JPEG8 codec to JPEG and deprecate JPEG8 alias (breaking).

• Rename codec parameter of imread and imwrite to imagecodec (breaking).

• Rename ultrahdr_encode_jpeg parameters and metadata keys (breaking).

• Move Brunsli JPEG transcoding to brunsli_encode_jpeg/decode_jpeg (breaking).

• Remove LJPEG fallback from jpeg_decode and jpeg_encode (breaking).

• Remove Python bz2 module fallback from bz2_encode and bz2_decode.

• Remove RGB565 color spaces from JPEG and MOZJPEG codecs (breaking).

• Remove planar auto-detection in jpeg2k_encode and htj2k_encode (breaking).

• Reject read-only output arrays in decoders (breaking).

• Return 1D uint8 view or byte memoryview of user-provided out (breaking).

• Reject bitspersample > 26 in jpeg2k_encode (breaking).

• Reject invalid colorspace and subsampling in JPEG encoders (breaking).

• Reject non-identity cICP matrix coefficients in PNG/APNG encoders (breaking).

• Reject non-contiguous output arrays in cms_transform (breaking).

• Reject unused whitepoint and primaries arguments in cms_profile (breaking).

• Reject unknown codec names in register_codecs.

• Reject object and zero itemsize dtypes in array codecs.

• Change imread return_codec parameter to info (breaking).

• Change integer out parameter to exact output size in all encoders (breaking).

• Change mozjpeg_decode to alias of jpeg_decode (breaking).

• Change jpegxl_encode/decode_jpeg options to keyword-only (breaking).

• Change BLOSC2/B2ND parameters and enums to match python-blosc2 (breaking).

• Change packints to pack 16, 32, and 64-bit integers big-endian (breaking).

• Change webp_encode default to lossy if level is specified (breaking).

• Change htj2k_encode resolutions to number of resolution levels (breaking).

• Change ISAL.COMPRESSION.SPEED to level 0 (breaking).

• Change numcodecs Jpegxl lossless default to None (breaking).

• Change meshopt_encode default level to 2 and use vertex codec v1.

• Change ultrahdr_encode default gainmap scale to library default.

• Change b2nd_decode to disable threading.

• Change BMP, PCX, and TGA codecs to thread-safe C libraries.

• Change imread to try APNG for PNG and WIC for camera raw files.

• Change AVIF creation times and cms_profile creation date to constant.

• Derive jpeg2k_encode default colorspace from image layout (breaking).

• Derive jpeg2k_encode color samples from colorspace parameter.

• Derive JPEG default color space from CMYK and extended RGB input.

• Convert CIELab to RGB in jpeg2k_decode (breaking).

• Add JPEGLI codec based on jpegli library (Windows only).

• Add iminfo function and info functions to many codecs.

• Add imagecodecs.typing module with type aliases.

• Add JpegCodec implementing the zarr-extensions jpeg spec.

• Add more filters and codecs to BLOSC2/B2ND (#163).

• Add jpeg_transcode and jpeg_merge functions (#160).

• Add scale parameter to jpeg_decode (#159).

• Add iccprofile parameter to JPEG, MOZJPEG, AVIF, and HEIF encoders.

• Add hasalpha parameter to HEIF and JPEGXL encoders.

• Add whitepoint and gamma parameters to jpegxl_encode.

• Add primaries, transfer, whitepoint, and gamma parameters to jpegxl_decode.

• Add planar parameter to jpegls_encode and jpegls_decode functions.

• Add pixelformat parameter to jpegxr_decode.

• Add extrasample parameter to jpeg2k_encode and write JP2 alpha channels.

• Add option to create wavpack correction data.

• Add hc parameter to lz4h5_encode.

• Add byteorder parameter to PixarLog codecs.

• Add displayp3, rec2020, sgray profiles and named curves to cms_profile.

• Add new encoder parameters to numcodecs and zarr codecs.

• Support typed contiguous output buffers in byte decompressors.

• Support negative index in AVIF, HEIF, APNG, and EXR decoders (breaking).

• Support non-native byte order input in most array codecs.

• Support non-native byte order output in PCODEC, SPERR, and SZ3 decoders.

• Support bytes-like ICC profiles in CMS functions.

• Support short and prefixed codec names in register_codecs.

• Support LERC blobs that use noData values (via lerc_decode_4D).

• Support interrupting zopfli_encode.

• Support zero delay and combined filters in APNG/PNG.

• Support more DDS DX10 formats.

• Support multi-member and padded GZIP streams and raw DEFLATE without size.

• Support uniformly subsampled components in jpeg2k_decode.

• Support 16-bit gray, 16-bit RGB, and gray-alpha images in spng_decode.

• Support 15/16-bit colormaps and right-to-left images in tga_decode.

• Support negative minexp, non-native byte order, and dtype strings in ZFP.

• Improve parameter validation, error messages, and check functions.

• Improve documentation.

• Improve type hints.

• Fix image layout of samples misinterpreted as frames.

• Fix zarr/numcodecs codecs shape handling, serialization, and Cms metadata.

• Fix photometric enum handling in HEIF, JPEGXL, APNG, and TIFF encoders.

• Fix RGBE, ULTRAHDR, QUANTIZE, and TIFF colormap with non-native byte order.

• Fix silent truncation and wrong checksums with data larger than 4 GB.

• Fix silent data truncation in LZMA, LZ4F, LZ4H5, BZ2, SZIP, and AEC codecs.

• Fix JPEGXR, JPEGXS, LJPEG encoders silently truncating output to small out.

• Fix decoding concatenated streams in LZMA and BZ2 codecs.

• Fix decoding highly compressible data in LZ4, Brotli, and AEC codecs.

• Fix crashes, out-of-bounds access, and writes to read-only buffers in IMCD.

• Fix aec_encode signedness of int8 and byte-order prefixed buffers.

• Fix apng_decode alpha compositing and apng_encode delays > 65535 ms.

• Fix (a)png_decode accepting truncated input or missing IEND chunk.

• Fix interlace handling in png_decode and apng_decode.

• Fix bitshuffle codecs ignoring itemsize of numpy arrays (breaking).

• Fix bmp_decode of bitfields not 8 bits and segfaults with zero channel mask.

• Fix CCITT decoders with 1D, ND, or buffer output.

• Fix ccittfax4_decode infinite loop on crafted input (#158).

• Fix cms_transform of gray volumes and big-endian floats, cms_info of v4.

• Fix thread-safety of error logging in cms_transform and cms_profile_validate.

• Fix decoding DDS cubemaps, texture arrays, and odd-sized textures.

• Fix eer_decode dropping last code and with invalid parameters (#162).

• Fix exr_encode default DWA and LJ2K compression levels.

• Fix float24_encode rounding overflow and directed rounding of large values.

• Fix gif_encode color resolution and gif_decode disposal and frame index.

• Fix h5checksum functions ignoring value and racing CRC table (breaking).

• Fix heif_decode of monochrome images.

• Fix isal_decode ignoring checksum errors and isal_crc32c non-standard values.

• Fix jpegsof3_decode OOB reads, uint8 wraparound, zero dimensions (#157).

• Fix ljpeg_decode and jpegsof3_decode ignoring point transform.

• Fix ljpeg_decode returning wrong samples with restart intervals.

• Fix jpegxl_decode returning uninitialized frames with invalid index.

• Fix jpegxs_decode hanging on truncated codestreams.

• Fix jpegxs_encode silently corrupting data deeper than 14 bits (breaking).

• Fix lzham_encode, lzfse_decode, and lzf_decode failing on specific data.

• Fix lzw_decode output truncation beyond 4 GB.

• Fix meshopt_decode ignoring shape and dtype if out is specified.

• Fix quanttable and progressive parameters of mozjpeg_encode.

• Fix packbits_encode quadratic runtime and silently truncated output.

• Fix pcodec_encode failing with small pagesize.

• Fix pglz_decode truncating output and reading past input (breaking).

• Fix pixarlog_decode returning uninitialized rows and failing on long strips.

• Fix plio_encode silently truncating floats.

• Fix quantize_encode corrupting non-finite values and with too large nsd.

• Fix rcomp_encode crash with nblock <= 0 and too small output estimate.

• Fix rgbe_encode/decode output size and dtype, read-only out, invalid values.

• Fix snappy_encode requiring level argument.

• Fix sperr_decode of single-slice 3D data, short headers, and ignored dtype.

• Fix sz3_decode heap overflow and uninitialized output with mismatched shape.

• Fix tiff_encode writing non-deterministic gap bytes.

• Fix tiff_decode silently accepting incomplete strip data.

• Fix wavpack_encode of unsigned and non-native byte order data (breaking).

• Fix webp_encode out-of-bounds reads with leading frame dimensions.

• Fix WIC pixel formats, frame shapes, and conversion crashes (breaking).

• Fix zfp_decode of data with full header when shape and dtype are specified.

• Fix ZSTD1 and CHUNKED codecs with empty, truncated, or plain Zstd data.

• Fix memory safety issues (buffer overflow, memory leaks, etc).

• Fix many other issues.

2026.10.10

• Reject 0-D input to array codecs (#151, breaking).

• Reject bitspersample outside dtype range (breaking).

• Reject dtype too wide for bitspersample (#153, breaking).

• Reject big-endian arrays in many codecs.

• Add skipres parameter to jpeg2k_decode (#155).

• Add bitspersample parameter to htj2k_encode (#153).

• Add bitspersample and color transformation parameter to jpegls_encode (#150).

• Add option to write SPIFF header in jpegls_encode (breaking).

• Add perceptualheuristics parameter to jpegxl_encode (#149).

• Add numthreads parameter to zstd_encode and zstd1_encode.

• Add gainmap_gamma, gainmap_level, and multichannel to ultrahdr_encode.

• Add ultrahdr_encode_jpeg and ultrahdr_decode_jpeg functions.

• Add colorinteropid parameter to exr_encode.

• Add compression level parameter to snappy_encode (require Snappy 1.3).

• Add contentsize parameter to lz4f_encode.

• Add chunked decoder to lz4f_decode, used when content size not in header.

• Add ZSTD and LJ2K compression to EXR codec (require OpenEXR 3.5).

• Add colorspace parameter to qoi_encode.

• Add codec parameter to avif_decode.

• Add numthreads parameter to heif_encode and heif_decode.

• Add rgbe_info function, and orientation field to rgbe_header_info C struct.

• Set GIF background alpha to 0 when alpha channel is present (breaking).

• Set JPEG8 lossless data precision to 16 for uint16 by default.

• Set AVIF encoder default speed to match avifenc (breaking).

• Enable writing lossy monochrome AVIF images.

• Update OPENZL codec to FrameInfo API (require OpenZL 0.3.0).

• Support more pixelformats in jpegxr_decode.

• Avoid copy of non-planar input in jpeg2k_encode.

• Avoid extra copy in CZI hilo unpacking.

• Avoid memset on CLEAR in lzw_encode.

• Improve lzw_decode using literal table.

• Improve inner loops in bmp_encode.

• Improve HTJ2K error handling.

• Use uint64 accumulators in imcd_delta, imcd_xor, and imcd_packints_decode.

• Fix issues in static Pyodide builds.

2026.8.16

• …

Refer to the CHANGES file for older revisions.

Notes

This library is largely a work in progress.

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

Works on little-endian platforms only.

Supported platforms are win_amd64, win_arm64, win32, 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, ccittfax3, ccittfax4, ccittrle, dds, dicomrle, eer, jpegsof3, lzo, and openzl codecs are currently decode-only.

The brunsli codec is distributed as source code only because the underlying library is 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.

Bundled source files in the 3rdparty folder are distributed under their own licenses.

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

When building against libjpeg or libjpeg_turbo < 3, set the environment variable IMAGECODECS_JPEG_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 \
libbrotli-dev libcharls-dev libdeflate-dev liblerc-dev libjpeg-dev \
libjxr-dev liblcms2-dev liblz4-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.

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.

Random access to parts of large segments is generally not supported.

Programming interface

Each codec is exposed through a set of module attributes, where CODEC and codec stand for the upper and lower case codec name, for example, JPEG2K and jpeg2k:

• CODEC: class with an available attribute indicating whether the codec is available in the build, and enums of codec constants.

• CodecError: exception raised by the codec functions.

• codec_version(): return version of the underlying library.

• codec_check(data): return whether data likely are encoded by the codec, or None if unknown.

• codec_info(data): return information about encoded data, such as shape and dtype, without decoding (not supported by all codecs).

• codec_encode(data, ..., out): return encoded data.

• codec_decode(data, ..., out): return decoded data.

The encode, decode, and info functions of codecs not available in the build raise DelayedImportError. Functions not implemented by a codec raise NotImplementedError.

Encode functions take numpy arrays or bytes-like objects and return bytes-like encoded data. Decode functions take bytes-like encoded data and return numpy arrays (image and array codecs) or bytes-like objects (byte compressors and filters).

The optional out parameter of encode and decode functions controls the output: None lets the codec allocate the output; bytes or bytearray select the type of the allocated output; an integer specifies the output size; a writable, contiguous buffer receives the output directly. Functions returning numpy arrays return a new array, or out or a view of it with the decoded shape and dtype. Functions returning bytes-like objects return a new bytes or bytearray object, or a view of the provided out buffer: a 1D uint8 view of a numpy array, a byte memoryview of other buffers, or the bytearray itself if completely filled. The length of the returned object is the number of bytes written.

Some codecs deviate from these rules, for example, filters and shufflers may return numpy arrays from encode functions, and some functions return tuples. Refer to the docstrings and type hints of individual functions.

Additional functions, such as checksums (zlib_crc32), color management (cms_transform, cms_profile), JPEG transcoding (jpeg_transcode, jpeg_merge, jpegli_transcode, jpegxl_encode_jpeg), codec initialization (htj2k_init), and the high level imread, imwrite, and iminfo functions do not follow the codec schema.

Examples

Import the JPEG2K codec used in these examples:

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

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 contain a JPEG 2000 stream:

>>> jpeg2k_check(encoded)
True

Obtain information about the encoded image:

>>> jpeg2k_info(encoded)
{..., 'shape': (256, 256, 3), 'dtype': dtype('uint8'), ...}

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

Transform the decoded image from sRGB to linear RGB:

>>> from imagecodecs import cms_transform, cms_profile
>>> transformed = cms_transform(
...     decoded, cms_profile('srgb'), cms_profile('linearrgb')
... )
>>> transformed.shape
(256, 256, 3)

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

>>> from imagecodecs import dicomrle_encode
>>> dicomrle_encode(array)
Traceback (most recent call last):
 ...
NotImplementedError: dicomrle_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 format 2 (legacy) array using numcodecs:

>>> import zarr
>>> from imagecodecs.numcodecs import register_codecs, Jpeg2k
>>> register_codecs(['jpeg2k'])
>>> zarr.zeros(
...     (4, 5, 512, 512, 3),
...     chunks=(1, 1, 256, 256, 3),
...     dtype='u2',
...     compressor=Jpeg2k(bitspersample=10),
...     zarr_format=2,
... )
<Array ... shape=(4, 5, 512, 512, 3) dtype=uint16>

Create a Delta-LZW compressed Zarr format 3 array using native zarr codecs:

>>> from imagecodecs.zarr import register_codecs, Delta, Lzw
>>> register_codecs(['delta', 'lzw'])
>>> zarr.zeros(
...     (4, 5, 512, 512, 3),
...     chunks=(1, 1, 256, 256, 3),
...     dtype='u1',
...     codecs=[Delta(), zarr.codecs.BytesCodec(), Lzw()],
... )
<Array ... shape=(4, 5, 512, 512, 3) dtype=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 using kerchunk:

>>> store.write_fsspec(
...     'temp.json',
...     url='file://',
...     codec_id='imagecodecs_jpeg2k',
...     zarr_format=3,
... )
>>> register_codecs(['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)...

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

python -m imagecodecs _test.jp2