pyheif

Installation methods vary by operating system. Note that Windows is not supported.

Linux (Simple Installation)

Installs a manylinux2014 wheel. This method does not work with Alpine Linux.

MacOS (From Source)

Requires libffi and libheif installed via Homebrew.

Linux (From Source)

Requires system dependencies for libffi, libheif, and libde265 via your package manager before installing from the git repository.

# Linux Simple
pip install --upgrade pip
pip install pyheif

# MacOS
brew install libffi libheif
pip install git+https://github.com/carsales/pyheif.git

# Linux Source
apt install libffi libheif-dev libde265-dev
# OR
yum install libffi libheif-devel libde265-devel
pip install git+https://github.com/carsales/pyheif.git

To manipulate HEIF data using the Pillow library, convert the HeifImage using Image.frombytes.

Note: The mode property must be passed twice: once as the mode argument of frombytes and once as the mode argument of the raw decoder.

from PIL import Image
import pyheif

heif_file = pyheif.read("IMG_7424.HEIC")
image = Image.frombytes(
    heif_file.mode, 
    heif_file.size, 
    heif_file.data,
    "raw",
    heif_file.mode,
    heif_file.stride,
    )

# Example: Save as JPEG
image.save("IMG_7424.jpg", "JPEG")

Use pyheif.open_container(path_or_bytes) to access the full HEIF container, which may include multiple images, depth maps, or auxiliary images. It accepts the same input types as pyheif.read().

Returns a HeifContainer object.

Use pyheif.read(path_or_bytes) to extract the primary image from a HEIF file.

Supported input types:

• A string file path
• A pathlib.Path object
• bytes or bytearray containing HEIF content
• A file-like object with a .read() method returning bytes

Returns a HeifImage object.

import pyheif

# Using a file path:
heif_file = pyheif.read("IMG_7424.HEIC")

# Or using bytes directly:
heif_file = pyheif.read(open("IMG_7424.HEIC", "rb").read())

The HeifImage object represents a decoded HEIF image and contains the following properties:

• mode: The image mode (e.g., "RGB" or "RGBA")
• size: A (width, height) tuple of integers
• data: The raw decoded file data as bytes
• metadata: A list of metadata dictionaries
• color_profile: A color profile dictionary
• stride: The number of bytes in a row of decoded file data
• bit_depth: The number of bits in each component of a pixel

The HeifContainer object provides access to all images within a HEIF file. Properties include:

• primary_image: The HeifTopLevelImage object of the primary image.
• top_level_images: A list of all HeifTopLevelImage objects in the container.

A HeifTopLevelImage represents an individual image entry in a container. Properties include:

• id: The image ID
• image: The UndecodedHeifImage or HeifImage object
• is_primary: Boolean indicating if this is the primary image
• depth_image: The HeifDepthImage (if present)
• auxiliary_images: A list of HeifAuxiliaryImage objects

A HeifDepthImage represents a depth map associated with an image. Properties include:

• id: The image ID
• image: The UndecodedHeifImage or HeifImage object

A HeifAuxiliaryImage represents an auxiliary image (like a thumbnail or secondary view) in a container. Properties include:

• id: The image ID
• image: The UndecodedHeifImage or HeifImage object
• type: A string indicating the type of auxiliary image