---
id: pyheif
version: "0.8.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# pyheif — Python 3.6+ interface to libheif library

License: permissive · Maintenance: active · Downloads: 163.9K/mo

## 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 above — 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

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

- License: not declared (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 163.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

heif heic image reader, read heic files python, heif image decoder, convert heic to raw pixels, heif container parser, apple heic support, libheif python wrapper, image-format, heic-heif, cffi-binding

[View on SkillFed](https://skillfed.io/packages/pyheif) · [View on PyPI](https://pypi.org/project/pyheif/)