Image transformation, compression, and decompression codecs

2026.3.6 · active · verified Sat Apr 11

Imagecodecs is a Python library that provides block-oriented, in-memory buffer transformation, compression, and decompression functions for various image and scientific data formats. It wraps numerous C libraries to support a wide array of codecs, including Zlib, JPEG, PNG, WebP, AVIF, and many others. It is actively maintained with frequent releases, currently at version 2026.3.6, and primarily depends on NumPy.

Warnings

breaking The API is explicitly stated as not stable and may change between revisions. Users should expect breaking changes and consult release notes before upgrading, especially for major versions.
Fix: Always check the `CHANGES` file or release notes on GitHub/PyPI for specific breaking changes when upgrading.
breaking Recent versions (e.g., 2026.3.6) enforce positional-only and keyword-only parameters for many functions. This can break older code that relies on keyword arguments where positional-only is now required.
Fix: Review function signatures in documentation and adjust calls to explicitly use positional or keyword arguments as required by the new definitions.
breaking Support for older Python versions is frequently dropped. For example, Python <= 3.10 was dropped in 2025.8.2, and Python 3.11 was deprecated in 2025.11.11.
Fix: Maintain an up-to-date Python environment (>=3.11 for current version) and regularly check `imagecodecs` requirements before upgrading the library.
breaking Many codec-specific parameters have been renamed or had their behavior altered across versions (e.g., `jpegxl_encode` level, `avif_encode` maxthreads/numthreads, `lerc_encode` planarconfig/planar). Additionally, many constants have been replaced by enums.
Fix: Consult the `CHANGES` file for detailed information on parameter renames and behavior changes for specific codecs you are using.
gotcha Building `imagecodecs` from source can be challenging due to its numerous external C library dependencies. Pre-built wheels are highly recommended for most users. Some codecs might be decode-only or unavailable on certain platforms/architectures.
Fix: Prefer installing pre-built wheels from PyPI (`pip install imagecodecs[all]`) or Anaconda/Conda-forge. On Windows, ensure the latest Microsoft Visual C++ Redistributable is installed.

Install

pip install -U "imagecodecs[all]" Install with all optional dependencies (recommended)
pip install -U imagecodecs Install core library only

Imports

jpeg_encode
```
from imagecodecs import jpeg_encode
```
png_decode
```
from imagecodecs import png_decode
```
imagecodecs
```
import imagecodecs
```
Common to import the module directly to access various codec functions like `imagecodecs.png_encode`.
Jpeg2k
```
from imagecodecs.numcodecs import Jpeg2k
```
Codec classes for `numcodecs` integration are found in `imagecodecs.numcodecs` and need explicit registration.

Quickstart

This quickstart demonstrates encoding a NumPy array representing an image into a PNG byte string and then decoding it back. It verifies that the original and decoded images are identical.

import numpy as np
from imagecodecs import png_encode, png_decode

# Create a dummy image (e.g., 100x100 grayscale image)
image_data = np.arange(100 * 100, dtype=np.uint8).reshape((100, 100))

# Encode the image to PNG format (bytes)
encoded_data = png_encode(image_data)
print(f"Encoded data size: {len(encoded_data)} bytes")

# Decode the PNG data back to a NumPy array
decoded_image = png_decode(encoded_data)
print(f"Decoded image shape: {decoded_image.shape}, dtype: {decoded_image.dtype}")

# Verify data integrity
assert np.array_equal(image_data, decoded_image)
print("Image encoded and decoded successfully!")

view raw JSON →