PyHEIF

0.8.0 · active · verified Thu Apr 16

PyHEIF is a Python 3.6+ interface to the `libheif` C library, enabling decoding of HEIF (High Efficiency Image Format) and HEIC images. It facilitates converting HEIF/HEIC images to raw pixel data, commonly used with libraries like Pillow. The current version is 0.8.0, with releases typically tied to Python version support and `libheif` updates, as well as new features.

Common errors

```
OSError: Could not find libheif.so (or libheif.dylib / heif.dll)
```
cause The `libheif` shared library is not installed on the system or is not located in a standard search path where `pyheif` can find it.

fix Install `libheif` via your system's package manager. For Debian/Ubuntu: `sudo apt install libheif-dev`. For macOS: `brew install libheif`. For Windows, consider `vcpkg install libheif:x64-windows` or manual installation.
```
pyheif.error.HeifError: Invalid HEIF file: 'Not a HEIF file' (Code: 1)
```
cause The provided file is either not a valid HEIF/HEIC image, is corrupted, or uses a HEIF profile not supported by the underlying `libheif` version.

fix Verify that the input file is a correctly formatted HEIF/HEIC image. Check its integrity and ensure it's not a different image format with a `.heic` extension. Update `libheif` to the latest version if possible.
```
AttributeError: 'HeifContainer' object has no attribute 'mode'
```
cause After `pyheif` 0.7.0, `pyheif.read()` returns a `HeifContainer` object when a HEIF file contains multiple images. `HeifContainer` itself does not have direct image attributes like `mode`, `data`, `width`, or `height`.

fix If `pyheif.read()` returns a `HeifContainer`, you need to access individual `HeifFile` objects within it. Iterate using `for heif_file in heif_container.heif_files:` or get the primary image via `heif_container.primary_image` to access its attributes.

Warnings

gotcha PyHEIF is a wrapper around the native `libheif` C library. You *must* install `libheif` on your system for `pyheif` to function. `pip install pyheif` only installs the Python bindings.
Fix: Install `libheif` via your system's package manager (e.g., `sudo apt install libheif-dev` on Debian/Ubuntu, `brew install libheif` on macOS, `vcpkg install libheif` on Windows) before installing `pyheif`.
breaking Starting with `pyheif` 0.7.0, the `pyheif.read()` function can return either a `HeifFile` object (for single images) or a `HeifContainer` object (for HEIF files containing multiple images). Code expecting only `HeifFile` attributes directly from `pyheif.read()` will break if processing multi-image HEIFs.
Fix: Check the type of the object returned by `pyheif.read()`. If it's a `HeifContainer`, iterate through `heif_container.heif_files` or access `heif_container.primary_image` to get individual `HeifFile` objects before accessing image attributes like `mode` or `data`.
gotcha Currently, `pyheif` only supports decoding HEIF images. There is no built-in functionality for encoding or creating HEIF/HEIC files.
Fix: If HEIF encoding is required, consider using other tools or libraries that specifically offer encoding capabilities.

Install

pip install pyheif Install PyHEIF

Imports

read
```
from pyheif import read
```

Quickstart

This quickstart demonstrates how to decode a HEIF/HEIC image using `pyheif` and convert it into a Pillow `Image` object. It also shows how to handle both single-image and multi-image HEIF files introduced in `pyheif` 0.7.0. The decoded image is then saved as a PNG file. Remember to replace 'example.heic' with a path to a valid HEIC file.

import pyheif
from PIL import Image
import os

# This example assumes you have an 'example.heic' file.
# For a real scenario, replace 'example.heic' with your HEIF/HEIC file path.
# If you don't have one, you might need to create a dummy file or download one.
# For local testing without a file, this would fail, so ensure file exists.
# HEIF files often come from iPhones or other modern cameras.

try:
    # Read the HEIF file. This can return HeifFile or HeifContainer.
    heif_object = pyheif.read("example.heic")

    if isinstance(heif_object, pyheif.HeifContainer):
        # Handle multiple images (e.g., burst photos, depth maps)
        print(f"File contains {len(heif_object.heif_files)} images.")
        primary_image = heif_object.primary_image
    else:
        # Single image file
        primary_image = heif_object

    # Convert to Pillow Image
    # The 'raw' decoder requires mode and stride matching the heif_file output
    pillow_image = Image.frombytes(
        primary_image.mode,
        (primary_image.width, primary_image.height),
        primary_image.data,
        "raw",
        primary_image.mode,
        primary_image.stride,
    )

    # Save the image as PNG
    output_path = "output_image.png"
    pillow_image.save(output_path, "PNG")
    print(f"Successfully decoded and saved image to {output_path}")

except FileNotFoundError:
    print("Error: 'example.heic' not found. Please create or provide a valid HEIC file path.")
except pyheif.error.HeifError as e:
    print(f"Error decoding HEIF file: {e}")
except ImportError:
    print("Error: Pillow not installed. Please install with 'pip install Pillow'.")

view raw JSON →