Install & Compatibility
Where this runs
tested against v2025.3.30 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 6.9s · import 0.247s · 337MB
314MB installed
● package 314MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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!")
Debug
Known issues
breakingThe 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.fixAlways check the `CHANGES` file or release notes on GitHub/PyPI for specific breaking changes when upgrading.
affects: All versions, ongoing
breakingRecent 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.fixReview function signatures in documentation and adjust calls to explicitly use positional or keyword arguments as required by the new definitions.
affects: >=2026.3.6
breakingSupport 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.fixMaintain an up-to-date Python environment (>=3.11 for current version) and regularly check `imagecodecs` requirements before upgrading the library.
affects: All versions, ongoing
breakingMany 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.fixConsult the `CHANGES` file for detailed information on parameter renames and behavior changes for specific codecs you are using.
affects: Various, especially >=2021.11.20
gotchaBuilding `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.fixPrefer 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.
affects: All versions
Upgrade
Version history
2026.8.16latest on PyPI · released Aug 15, 2026
Audit
Dependencies
numpyrequiredCore dependency for array manipulation and image data handling.
numcodecsoptionalOptional, provides Zarr file format 2 compatible codecs and integration.