pyheif

What it is and what it does

pyheif is a Python wrapper around the libheif C library that lets you read HEIF and HEIC image files—the modern container formats used by Apple devices. It exposes the decoded image data (pixel bytes, dimensions, color mode) along with metadata and the full container structure, so you can extract images and their properties programmatically.

The package is read-only: it decodes HEIF containers and images but does not write them. It works on Linux and macOS with prebuilt wheels for modern Python versions (3.6+), though building from source requires system libraries. The decoded image data can be passed directly to Pillow for further manipulation or conversion to other formats like JPEG.

Use it for:

• Extract pixel data from iPhone or iPad photos (HEIC format) for processing in Python image libraries.
• Batch convert HEIC files to JPEG or PNG by reading with pyheif and saving via Pillow.
• Access metadata and color profiles embedded in HEIF files for archival or analysis.
• Parse HEIF container structure to enumerate all images, depth maps, and auxiliary images in a single file.
• Integrate HEIC support into web applications or image processing pipelines on Linux servers.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Reads HEIF/HEIC image files and exposes their decoded pixel data, metadata, and container structure through a Python interface to the libheif C library.

Yes, if you need to read HEIC/HEIF files on Linux or macOS. The package is actively maintained, has no known vulnerabilities, and fills a clear gap for Apple image format support. Install friction is moderate due to system library dependencies, but prebuilt wheels ease setup on standard Linux distributions. Not suitable for Windows or write-heavy workflows.

Install

pyheif on PyPI

pip install pyheif

uv add pyheif

poetry add pyheif

Installing pyheif

Before you install

Medium friction: requires precompiled wheels on Linux (manylinux2014 x86_64/aarch64) but needs system libraries (libheif, libde265, libffi) when building from source on macOS or Linux. Repository is active with recent commits and no Windows support.

License in practice

Permissive license allows commercial and private use without restriction, though exact license terms are not specified in the package metadata.

Quickstart

import pyheif

heif_file = pyheif.read("image.HEIC")
print(heif_file.mode, heif_file.size, len(heif_file.data))

Requires libheif, libde265, and libffi system libraries installed; not available on Windows; only reading is supported, not writing.

Verify before relying

• Whether cffi is automatically installed as a dependency or must be pre-installed separately.
• Performance characteristics when processing large HEIF files or containers with many images.
• Exact license identifier (Apache 2.0 inferred from classifier but not confirmed in metadata).

Package facts

Evidence: pyheif-0.8.0-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-pp310-pypy310_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-pp310-pypy310_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; pyheif-0.8.0-pp39-pypy39_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; pyheif-0.8.0-pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Keywords: heif, heic

Tags

More Graphics packages