{"id":1623,"library":"pillow-avif-plugin","title":"Pillow AVIF Plugin","description":"Pillow AVIF Plugin is a Python library that extends Pillow's image processing capabilities by adding support for the AVIF (AV1 Image File Format) format. It provides the ability to open, manipulate, and save AVIF images using the standard Pillow API. As of its current version 1.5.5, it actively integrates with the latest Pillow releases and underlying `libavif` codecs, receiving regular updates to maintain compatibility and performance.","status":"active","version":"1.5.5","language":"en","source_language":"en","source_url":"https://github.com/fdintino/pillow-avif-plugin/","tags":["Pillow","AVIF","image","plugin","codec","image processing"],"install":[{"cmd":"pip install pillow-avif-plugin","lang":"bash","label":"Install plugin"}],"dependencies":[{"reason":"This library is a plugin for Pillow and requires Pillow to be installed to function. It's a peer dependency, not explicitly listed in install_requires.","package":"Pillow","optional":false}],"imports":[{"note":"Standard Pillow import. The plugin registers itself upon import of `pillow_avif`.","symbol":"Image","correct":"from PIL import Image"},{"note":"Importing `pillow_avif` is necessary to register the AVIF image handler with Pillow. Without this import, Pillow will not recognize AVIF files.","wrong":"from pillow_avif import AvifImagePlugin # Not strictly wrong, but simple import is sufficient for registration","symbol":"pillow_avif","correct":"import pillow_avif"}],"quickstart":{"code":"from PIL import Image\nimport pillow_avif # Essential to register the plugin\nimport os\n\n# Create a dummy image for demonstration\nimg = Image.new('RGB', (100, 100), color = 'red')\n\n# Save as AVIF\noutput_filename = 'example.avif'\nimg.save(output_filename)\nprint(f\"Saved a red 100x100 AVIF image to {output_filename}\")\n\n# Open the AVIF image\nloaded_img = Image.open(output_filename)\nprint(f\"Loaded image format: {loaded_img.format}, size: {loaded_img.size}\")\n\n# Clean up (optional)\nos.remove(output_filename)","lang":"python","description":"This quickstart demonstrates how to save and load an AVIF image using Pillow after ensuring the `pillow_avif` plugin is imported, which registers the AVIF format handler with Pillow. Without `import pillow_avif`, `Image.open()` and `Image.save()` will not support AVIF files."},"warnings":[{"fix":"Always include `import pillow_avif` at the beginning of your script or module where you intend to work with AVIF images.","message":"The `pillow-avif-plugin` must be explicitly imported (`import pillow_avif`) for Pillow to recognize and handle AVIF files. Simply installing the package is not enough to activate the plugin.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you are using the latest version of `pillow-avif-plugin` (and ideally, Pillow as well) to maintain compatibility. Check the plugin's release notes for specific Pillow version requirements.","message":"Compatibility with specific Pillow versions can break between plugin releases. For example, `v1.5.2` addressed compatibility issues with Pillow 11.2.1. Running an older plugin version with a much newer Pillow (or vice-versa) might lead to errors or unexpected behavior.","severity":"breaking","affected_versions":"<1.5.2 with Pillow >=11.2.1"},{"fix":"Upgrade to `pillow-avif-plugin` version `1.5.0` or newer, which includes fixes to correctly convert AVIF `irot` and `imir` into EXIF orientation when decoding.","message":"Older versions of the plugin may incorrectly handle or lose image orientation metadata (EXIF `irot`/`imir`) during decoding or conversion, potentially resulting in images appearing rotated incorrectly when saved to other formats.","severity":"gotcha","affected_versions":"<1.5.0"},{"fix":"Ensure you are using the latest stable version of `pillow-avif-plugin`. These issues are typically resolved by updating the plugin, which often includes updated bundled `libavif` and compilation flags.","message":"Certain platform-specific issues, such as compiler errors (`incompatible-pointer-type`) or `illegal instruction segfault` on macOS ARM64, have occurred in past versions due to underlying `libavif` build processes.","severity":"gotcha","affected_versions":"<1.5.3 (compiler error), <1.4.6 (macOS ARM64 segfault)"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}