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.
Install & Compatibility
Where this runs
tested against v1.5.5 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AvifImagePlugin
✓ import pillow_avif
✗ from pillow_avif import AvifImagePlugin
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.
from PIL import Image
import pillow_avif # Essential to register the plugin
import os
# Create a dummy image for demonstration
img = Image.new('RGB', (100, 100), color = 'red')
# Save as AVIF
output_filename = 'example.avif'
img.save(output_filename)
print(f"Saved a red 100x100 AVIF image to {output_filename}")
# Open the AVIF image
loaded_img = Image.open(output_filename)
print(f"Loaded image format: {loaded_img.format}, size: {loaded_img.size}")
# Clean up (optional)
os.remove(output_filename)
Debug
Known issues
gotchaThe `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.fixAlways include `import pillow_avif` at the beginning of your script or module where you intend to work with AVIF images.
affects: All versions
breakingCompatibility 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.fixEnsure 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.
affects: <1.5.2 with Pillow >=11.2.1
gotchaOlder 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.fixUpgrade 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.
affects: <1.5.0
gotchaCertain 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.fixEnsure 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.
affects: <1.5.3 (compiler error), <1.4.6 (macOS ARM64 segfault)
Audit
Dependencies
PillowrequiredThis 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.