bigcat88/pillow_heif

What it solves

HEIF/HEIC is a modern image format that stores photos more efficiently than JPEG, but it is not natively supported by Python's popular Pillow imaging library. This project adds that missing support, letting Python developers read and write HEIF images directly through Pillow's familiar API.

How it works

It is a Python binding to libheif (a C library for HEIF/HEIC images) and is registered as a Pillow plugin. Once you call register_heif_opener(), any Pillow open/save operation works with .heic files. It can decode and encode 8-, 10-, and 12-bit images, handle metadata (EXIF, XMP, IPTC), support multiple images per file, thumbnails, tiled (grid) encoding, and depth images. It also allows direct access to raw decoded data and conversion to NumPy arrays.

Who it's for

Python developers working with HEIF images, especially those who need to process photos from modern devices (e.g., iPhones) in automated workflows, web apps, or image-processing pipelines. It is also useful for anyone who wants to convert between HEIF and other formats using Pillow.

Highlights

• Decodes and encodes HEIC files at 8, 10, and 12 bits per channel.
• Supports reading and writing EXIF, XMP, and IPTC metadata.
• Handles multiple images in one file, including a designated primary image.
• Adds or removes thumbnails and supports grid (tiled) encoding like Apple devices.
• Can read depth images (used for portrait effects) and auxiliary images (beta).
• One-line registration makes any Pillow code instantly HEIF-aware.
• Prebuilt wheels are available for macOS, Windows, Linux, and more.