Install & Compatibility
Where this runs
tested against v1.5.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.130s · 67.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.120s · 64MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
register_heif_opener
✓ from pillow_heif import register_heif_opener
This function registers HEIF support with Pillow's Image module. It must be called once before attempting to open HEIF files using PIL.Image.open.
Image
✓ from PIL import Image
Standard Pillow import for image manipulation after HEIF opener is registered.
This quickstart demonstrates how to register HEIF support with Pillow, open an existing HEIF/HEIC image, convert it to JPEG, and then save an image back into the HEIC format. Ensure you have an 'input.heif' file in your working directory or provide a path via `HEIF_INPUT_PATH` environment variable. The `os.environ.get` is used to make it runnable without hardcoding paths.
from PIL import Image
from pillow_heif import register_heif_opener
import os
# Register the HEIF opener once at the start of your application
register_heif_opener()
# --- Example: Open and convert a HEIF/HEIC image ---
heif_path = os.environ.get('HEIF_INPUT_PATH', 'input.heif')
output_path = os.environ.get('OUTPUT_JPEG_PATH', 'output.jpeg')
try:
# Open a HEIF image
heif_img = Image.open(heif_path)
print(f"Successfully opened HEIF image: {heif_path}")
print(f"Image format: {heif_img.format}, size: {heif_img.size}, mode: {heif_img.mode}")
# Convert and save to JPEG
# Note: HEIF often has 10-bit or 12-bit depth. For 8-bit formats like JPEG,
# Pillow will convert, potentially losing some detail.
if heif_img.mode == 'LA': # Handle monochrome with alpha
heif_img = heif_img.convert('L')
elif 'A' in heif_img.mode: # Remove alpha for JPEG
heif_img = heif_img.convert('RGB')
else:
heif_img = heif_img.convert('RGB') # Ensure RGB for JPEG
heif_img.save(output_path, quality=90)
print(f"Saved converted image to: {output_path}")
except FileNotFoundError:
print(f"Error: HEIF input file '{heif_path}' not found.")
print("Please ensure 'input.heif' exists or set HEIF_INPUT_PATH environment variable.")
except Exception as e:
print(f"An error occurred: {e}")
# --- Example: Create and save a HEIF/HEIC image (requires an input image first) ---
# This part assumes 'output.jpeg' was created or exists.
if os.path.exists(output_path):
try:
jpeg_img = Image.open(output_path)
heic_output_path = os.environ.get('OUTPUT_HEIC_PATH', 'generated.heic')
# Save as HEIC. You can specify encoder parameters in .info['heif_metadata']
jpeg_img.save(heic_output_path, quality=80, save_all=True)
print(f"Saved image back to HEIC: {heic_output_path}")
except Exception as e:
print(f"An error occurred while saving to HEIC: {e}")
else:
print(f"Skipping HEIC creation: '{output_path}' not found.")
Errors
Common errors & fixes
Failed building wheel for pillow-heif
The `pillow-heif` library requires system-level development headers for `libheif` and its dependencies (like `x265`, `aom`, `libde265`) to be installed for successful compilation, which `pip` cannot automatically manage.
fixOn Ubuntu/Debian, install `libheif-dev` using `sudo apt update && sudo apt install -y libheif-dev`. On macOS with Homebrew, run `brew install libheif`. For Windows, it's recommended to use prebuilt binaries by simply running `pip install pillow-heif` which usually fetches a wheel. If building from source is necessary on Windows, install MSYS2 and related libraries as per the official documentation.
PIL.UnidentifiedImageError: cannot identify image file 'path/to/image.heic'
Pillow does not natively support HEIC/HEIF formats. The `pillow-heif` library provides this support as a plugin, which must be explicitly registered with Pillow.
fixBefore opening HEIC files with `PIL.Image.open()`, you must import and call `register_heif_opener()` from `pillow_heif` once in your application.
```python
from PIL import Image
from pillow_heif import register_heif_opener
register_heif_opener()
image = Image.open('image.heic')
``` AttributeError: module 'pillow_heif' has no attribute 'register_avif_opener'
Starting with `pillow-heif` version 1.0.0, support for AVIF images was removed from this library because Pillow itself gained native AVIF support, making the `register_avif_opener` function obsolete.
fixRemove any calls to `pillow_heif.register_avif_opener()`. If you need to open AVIF files, ensure your Pillow version is recent enough (Pillow 9.1.0 or later for native AVIF support). If you specifically require the `pillow-heif` AVIF functionality, you may need to downgrade `pillow-heif` to a version prior to 1.0.0 (e.g., `pip install pillow-heif<1.0`).
Upgrade
Version history
1.5.0latest on PyPI · released Jul 22, 2026
Audit
Dependencies
No dependency data recorded yet.