{"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":"python","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,"search_vec":"'2026.3.6':64 'activ':56 'array':42 'avif':50 'block':15 'block-ori':14 'buffer':20 'c':36 'codec':6,44,74 'compress':3,22,72 'current':61 'data':31 'decompress':5,24,73 'depend':67 'format':32 'frequent':59 'function':25 'imag':1,28,70,77 'imagecodec':7 'in-memori':17 'includ':45 'jpeg':47 'librari':11,37 'maintain':57 'mani':52 'memori':19 'numer':35 'numpi':69,75 'orient':16 'other':53 'png':48 'primarili':66 'process':71 'provid':13 'python':10 'releas':60 'scientif':30,76 'support':39 'transform':2,21 'various':27 'version':63 'webp':49 'wide':41 'wrap':34 'zarr':78 'zlib':46","created_at":"2026-04-12T03:38:48.734207+00:00","updated_at":"2026-04-16T15:41:54.080399+00:00","problems":{"verify_error":"error: unexpected argument '- ' found\n\n  tip: to pass '- ' as a value, use '-- - '\n\nUsage: uv pip install [OPTIONS] <PACKAGE|--requirements <REQUIREMENTS>|--editable <EDITABLE>|--group <GROUP>>\n\nFor more information, try '--help'."},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2026.8.16","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.cgohlke.com","github":"https://github.com/cgohlke/imagecodecs","docs":null,"changelog":null,"pypi":"https://pypi.org/project/imagecodecs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-05","install_tag":null}}