{"id":8487,"library":"pyheif","title":"PyHEIF","description":"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.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/carsales/pyheif","tags":["image","heif","heic","decode","media","photography","image-processing"],"install":[{"cmd":"pip install pyheif","lang":"bash","label":"Install PyHEIF"}],"dependencies":[{"reason":"Requires system-level installation of the libheif library for image decoding and encoding capabilities. PyHEIF is a wrapper around this native library.","package":"libheif"}],"imports":[{"symbol":"read","correct":"from pyheif import read"}],"quickstart":{"code":"import pyheif\nfrom PIL import Image\nimport os\n\n# This example assumes you have an 'example.heic' file.\n# For a real scenario, replace 'example.heic' with your HEIF/HEIC file path.\n# If you don't have one, you might need to create a dummy file or download one.\n# For local testing without a file, this would fail, so ensure file exists.\n# HEIF files often come from iPhones or other modern cameras.\n\ntry:\n    # Read the HEIF file. This can return HeifFile or HeifContainer.\n    heif_object = pyheif.read(\"example.heic\")\n\n    if isinstance(heif_object, pyheif.HeifContainer):\n        # Handle multiple images (e.g., burst photos, depth maps)\n        print(f\"File contains {len(heif_object.heif_files)} images.\")\n        primary_image = heif_object.primary_image\n    else:\n        # Single image file\n        primary_image = heif_object\n\n    # Convert to Pillow Image\n    # The 'raw' decoder requires mode and stride matching the heif_file output\n    pillow_image = Image.frombytes(\n        primary_image.mode,\n        (primary_image.width, primary_image.height),\n        primary_image.data,\n        \"raw\",\n        primary_image.mode,\n        primary_image.stride,\n    )\n\n    # Save the image as PNG\n    output_path = \"output_image.png\"\n    pillow_image.save(output_path, \"PNG\")\n    print(f\"Successfully decoded and saved image to {output_path}\")\n\nexcept FileNotFoundError:\n    print(\"Error: 'example.heic' not found. Please create or provide a valid HEIC file path.\")\nexcept pyheif.error.HeifError as e:\n    print(f\"Error decoding HEIF file: {e}\")\nexcept ImportError:\n    print(\"Error: Pillow not installed. Please install with 'pip install Pillow'.\")\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"If HEIF encoding is required, consider using other tools or libraries that specifically offer encoding capabilities.","message":"Currently, `pyheif` only supports decoding HEIF images. There is no built-in functionality for encoding or creating HEIF/HEIC files.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"OSError: Could not find libheif.so (or libheif.dylib / heif.dll)"},{"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.","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.","error":"pyheif.error.HeifError: Invalid HEIF file: 'Not a HEIF file' (Code: 1)"},{"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.","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`.","error":"AttributeError: 'HeifContainer' object has no attribute 'mode'"}]}