Registry / serialization / pyheif

pyheif

JSON →
library0.8.0pypypi✓ verified 87d ago

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.

pip install pyheif
INSTALL
IMPORT
SIG · PYHEIF
P
pyheif
serializationpythonv0.8.0
Install
2.1s avg
Import
18ms
Disk
36MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.8.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
musl
glibc
py 3.10
✕ build_error
✓ 2.03s
py 3.11
✕ build_error
✓ 1.98s
py 3.12
✕ build_error
✓ 1.83s
py 3.13
✕ build_error
✕ build_error
py 3.9
✕ build_error
✓ 2.38s
36MB installed
● package 36MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

read
from pyheif import read

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'.")
Debug
Known issues
gotchaPyHEIF 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`.
affects: All versions
breakingStarting 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`.
affects: >=0.7.0
gotchaCurrently, `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.
affects: All versions
Errors
Common errors & fixes
OSError: Could not find libheif.so (or libheif.dylib / heif.dll)
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)
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'
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.
Upgrade
Version history
0.8.0latest on PyPI · released Sep 1, 2024
Audit
Dependencies
libheifrequiredRequires system-level installation of the libheif library for image decoding and encoding capabilities. PyHEIF is a wrapper around this native library.
Agent activity
33 hits · last 30 days
node
28
Resources
pyheif — pip install pyheif · libregistry