Pillow AVIF Plugin

1.5.5 · active · verified Thu Apr 09

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.

Warnings

gotcha 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.
Fix: Always include `import pillow_avif` at the beginning of your script or module where you intend to work with AVIF images.
breaking 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

pip install pillow-avif-plugin Install plugin

Imports

Image
```
from PIL import Image
```
Standard Pillow import. The plugin registers itself upon import of `pillow_avif`.
pillow_avif
```
import pillow_avif
```
Importing `pillow_avif` is necessary to register the AVIF image handler with Pillow. Without this import, Pillow will not recognize AVIF files.

Quickstart

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)

view raw JSON →