AVIF save fails

[b0ssi]

What did you do?

Open an image and attempt to export it in the AVIF format.

What did you expect to happen?

The export (save) to succeed.

What actually happened?

The following exception gets thrown:
ValueError: unknown file extension: .avif

What are your OS, Python and Pillow versions?

• OS: Arch Linux (rolling)
• Python: 3.13.3
• Pillow: 11.2.1

--------------------------------------------------------------------
Pillow 11.2.1
Python 3.13.3 (main, Apr  9 2025, 07:44:25) [GCC 14.2.1 20250207]
--------------------------------------------------------------------
Python executable is /usr/bin/python3
System Python files loaded from /usr
--------------------------------------------------------------------
Python Pillow modules loaded from /usr/lib/python3.13/site-packages/PIL
Binary Pillow modules loaded from /usr/lib/python3.13/site-packages/PIL
--------------------------------------------------------------------
--- PIL CORE support ok, compiled for 11.2.1
--- TKINTER support ok, loaded 8.6
--- FREETYPE2 support ok, loaded 2.13.3
--- LITTLECMS2 support ok, loaded 2.17
--- WEBP support ok, loaded 1.5.0
*** AVIF support not installed
--- JPEG support ok, compiled for libjpeg-turbo 3.1.0
--- OPENJPEG (JPEG2000) support ok, loaded 2.5.3
--- ZLIB (PNG/ZIP) support ok, loaded 1.3.1
--- LIBTIFF support ok, loaded 4.7.0
--- RAQM (Bidirectional Text) support ok, loaded 0.10.2
--- LIBIMAGEQUANT (Quantization method) support ok, loaded 4.2.2
--- XCB (X protocol) support ok
--------------------------------------------------------------------

import PIL
img = PIL.open("image.jpg")
img.save("image.avif")

As the PIL report indicates AVIF support is, apparently, not installed. However:

• PIL does log that it's importing its plugin: DEBUG - Importing AvifImagePlugin
• libavif is installed on this Arch distribution (1.3.0-1)

What could the reasons be for the failing export? Could this be an issue that might need to be delegated to the maintainer of the pillow package on Arch?

Many thanks for looking into this!

P.S.: The Arch package adding support for AVIF was not installed (python-pillow-avif-plugin), so no surprise there. However, installing it still does not seem to make any difference. if it is of any help, the file contents of the avif plugin package are as follows:

python-pillow-avif-plugin /usr/
python-pillow-avif-plugin /usr/lib/
python-pillow-avif-plugin /usr/lib/python3.13/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/AvifImagePlugin.py
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__init__.py
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__pycache__/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__pycache__/AvifImagePlugin.cpython-313.opt-1.pyc
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__pycache__/AvifImagePlugin.cpython-313.pyc
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__pycache__/__init__.cpython-313.opt-1.pyc
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/__pycache__/__init__.cpython-313.pyc
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif/_avif.cpython-313-x86_64-linux-gnu.so
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/METADATA
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/RECORD
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/WHEEL
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/licenses/
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/licenses/LICENSE
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/top_level.txt
python-pillow-avif-plugin /usr/lib/python3.13/site-packages/pillow_avif_plugin-1.5.2.dist-info/zip-safe
python-pillow-avif-plugin /usr/share/
python-pillow-avif-plugin /usr/share/licenses/
python-pillow-avif-plugin /usr/share/licenses/python-pillow-avif-plugin/
python-pillow-avif-plugin /usr/share/licenses/python-pillow-avif-plugin/LICENSE

P.P.S.: I seem to be seeing the same symptoms through a virtualenv (pip packages for both, pillow and avif-plugin).

[b0ssi]

I came across a suggestion to import pillow_avif, which resolves the issue. This seems a bit counter intuitive and reading the documentation (https://pillow.readthedocs.io/en/stable/handbook/image-file-formats.html) I didn't come across any obvious mentioning of (some) formats requiring explicit imports to add support. Did I just read past a relevant section or would it possibly be a good idea to add this to relevant points in the documentation? The file formats page I link to above seems an obvious place but there might be others which I might have missed.

[radarhere]

Hi. When you run import pillow_avif, it means that you are using https://pypi.org/project/pillow-avif-plugin/, rather than Pillow's builtin AVIF support. This same package is what https://archlinux.org/packages/extra/x86_64/python-pillow-avif-plugin/ is connected to.

As to why Pillow isn't supporting AVIF images by itself, as background information, the release notes for Pillow 11.2.1 state (emphasis mine),

Pillow can now read and write AVIF images when built from source with libavif 1.0.0 or later.

We initially added AVIF support to our prebuilt wheels, but removed it due to file size concerns. You can read #8856 if you'd like to know more.

If you're using our prebuilt wheels, then that is why. If the Arch package is building its own wheels, then it is possible that they were put off by that back-and-forth, or maybe they just haven't noticed that Pillow 11.2.1 supports AVIF. If you want to report to https://archlinux.org/packages/extra/x86_64/python-pillow/ that AVIF is not supported, then that doesn't seem unreasonable.

So, as far as using Pillow by itself, you can
a) stop using the prebuilt wheels and compile Pillow yourself, or
b) start a discussion with the Arch package maintainer, or
c) you can wait for the release of Pillow 11.3.0, due out on July 1. In that release, we plan to include AVIF support in our wheels through #8858. At that point, the Arch package maintainer may feel more inclined to support the AVIF format.

[b0ssi]

Hi @radarhere,

interesting, thanks for your detailed reply; that all makes sense. Good you mention the distinction between internal support you have been and are working on and the independent support through the plugin, that clarifies some confusion.

I scanned the PRs you reference briefly, good you found a point of reasonable compromise as a solution and looking forward to the 11.3.0 release that will return internal support. I might drop the maintainers a brief note and custom build in the meantime, many thanks again.

P.S.: This issue should be good to get closed off from my point of view.

[radarhere]

Pillow 11.3.0 has now been released with AVIF support in the wheels.