{"id":4049,"library":"imagecodecs","title":"Image transformation, compression, and decompression codecs","description":"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.","status":"active","version":"2026.3.6","language":"en","source_language":"en","source_url":"https://github.com/cgohlke/imagecodecs","tags":["image processing","compression","decompression","codec","numpy","scientific imaging","zarr"],"install":[{"cmd":"pip install -U \"imagecodecs[all]\"","lang":"bash","label":"Install with all optional dependencies (recommended)"},{"cmd":"pip install -U imagecodecs","lang":"bash","label":"Install core library only"}],"dependencies":[{"reason":"Core dependency for array manipulation and image data handling.","package":"numpy"},{"reason":"Optional, provides Zarr file format 2 compatible codecs and integration.","package":"numcodecs","optional":true}],"imports":[{"symbol":"jpeg_encode","correct":"from imagecodecs import jpeg_encode"},{"symbol":"png_decode","correct":"from imagecodecs import png_decode"},{"note":"Common to import the module directly to access various codec functions like `imagecodecs.png_encode`.","symbol":"imagecodecs","correct":"import imagecodecs"},{"note":"Codec classes for `numcodecs` integration are found in `imagecodecs.numcodecs` and need explicit registration.","symbol":"Jpeg2k","correct":"from imagecodecs.numcodecs import Jpeg2k"}],"quickstart":{"code":"import numpy as np\nfrom imagecodecs import png_encode, png_decode\n\n# Create a dummy image (e.g., 100x100 grayscale image)\nimage_data = np.arange(100 * 100, dtype=np.uint8).reshape((100, 100))\n\n# Encode the image to PNG format (bytes)\nencoded_data = png_encode(image_data)\nprint(f\"Encoded data size: {len(encoded_data)} bytes\")\n\n# Decode the PNG data back to a NumPy array\ndecoded_image = png_decode(encoded_data)\nprint(f\"Decoded image shape: {decoded_image.shape}, dtype: {decoded_image.dtype}\")\n\n# Verify data integrity\nassert np.array_equal(image_data, decoded_image)\nprint(\"Image encoded and decoded successfully!\")","lang":"python","description":"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."},"warnings":[{"fix":"Always check the `CHANGES` file or release notes on GitHub/PyPI for specific breaking changes when upgrading.","message":"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.","severity":"breaking","affected_versions":"All versions, ongoing"},{"fix":"Review function signatures in documentation and adjust calls to explicitly use positional or keyword arguments as required by the new definitions.","message":"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.","severity":"breaking","affected_versions":">=2026.3.6"},{"fix":"Maintain an up-to-date Python environment (>=3.11 for current version) and regularly check `imagecodecs` requirements before upgrading the library.","message":"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.","severity":"breaking","affected_versions":"All versions, ongoing"},{"fix":"Consult the `CHANGES` file for detailed information on parameter renames and behavior changes for specific codecs you are using.","message":"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.","severity":"breaking","affected_versions":"Various, especially >=2021.11.20"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}