Install & Compatibility
Where this runs
tested against v1.6.0 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 30.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.000s · 31MB
28MB installed
● package 28MB
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)
Upgrade
Version history
1.6.0latest on PyPI · released Jul 22, 2026
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.