{"id":1624,"library":"pillow-heif","title":"Pillow-HEIF","description":"Pillow-HEIF is a Python interface for the libheif library, enabling the Pillow (PIL Fork) imaging library to open and save HEIF (High Efficiency Image File Format) and HEIC images. The current version is 1.3.0 and the project maintains an active release cadence with frequent updates to bundled libraries and bug fixes.","status":"active","version":"1.3.0","language":"python","source_language":"en","source_url":"https://github.com/bigcat88/pillow_heif","tags":["image processing","HEIF","HEIC","Pillow","PIL","libheif"],"install":[{"cmd":"pip install pillow-heif","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This function registers HEIF support with Pillow's Image module. It must be called once before attempting to open HEIF files using PIL.Image.open.","symbol":"register_heif_opener","correct":"from pillow_heif import register_heif_opener"},{"note":"Standard Pillow import for image manipulation after HEIF opener is registered.","symbol":"Image","correct":"from PIL import Image"}],"quickstart":{"code":"from PIL import Image\nfrom pillow_heif import register_heif_opener\nimport os\n\n# Register the HEIF opener once at the start of your application\nregister_heif_opener()\n\n# --- Example: Open and convert a HEIF/HEIC image ---\nheif_path = os.environ.get('HEIF_INPUT_PATH', 'input.heif')\noutput_path = os.environ.get('OUTPUT_JPEG_PATH', 'output.jpeg')\n\ntry:\n    # Open a HEIF image\n    heif_img = Image.open(heif_path)\n    print(f\"Successfully opened HEIF image: {heif_path}\")\n    print(f\"Image format: {heif_img.format}, size: {heif_img.size}, mode: {heif_img.mode}\")\n\n    # Convert and save to JPEG\n    # Note: HEIF often has 10-bit or 12-bit depth. For 8-bit formats like JPEG,\n    # Pillow will convert, potentially losing some detail.\n    if heif_img.mode == 'LA': # Handle monochrome with alpha\n        heif_img = heif_img.convert('L')\n    elif 'A' in heif_img.mode: # Remove alpha for JPEG\n        heif_img = heif_img.convert('RGB')\n    else:\n        heif_img = heif_img.convert('RGB') # Ensure RGB for JPEG\n\n    heif_img.save(output_path, quality=90)\n    print(f\"Saved converted image to: {output_path}\")\n\nexcept FileNotFoundError:\n    print(f\"Error: HEIF input file '{heif_path}' not found.\")\n    print(\"Please ensure 'input.heif' exists or set HEIF_INPUT_PATH environment variable.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n# --- Example: Create and save a HEIF/HEIC image (requires an input image first) ---\n# This part assumes 'output.jpeg' was created or exists.\nif os.path.exists(output_path):\n    try:\n        jpeg_img = Image.open(output_path)\n        heic_output_path = os.environ.get('OUTPUT_HEIC_PATH', 'generated.heic')\n        # Save as HEIC. You can specify encoder parameters in .info['heif_metadata']\n        jpeg_img.save(heic_output_path, quality=80, save_all=True)\n        print(f\"Saved image back to HEIC: {heic_output_path}\")\n    except Exception as e:\n        print(f\"An error occurred while saving to HEIC: {e}\")\nelse:\n    print(f\"Skipping HEIC creation: '{output_path}' not found.\")\n","lang":"python","description":"This quickstart demonstrates how to register HEIF support with Pillow, open an existing HEIF/HEIC image, convert it to JPEG, and then save an image back into the HEIC format. Ensure you have an 'input.heif' file in your working directory or provide a path via `HEIF_INPUT_PATH` environment variable. The `os.environ.get` is used to make it runnable without hardcoding paths."},"warnings":[{"fix":"Upgrade Python to 3.10+ or use `pillow-heif<1.2.0`.","message":"Python 3.9 support was dropped in `v1.2.0`. Projects targeting Python 3.9 will need to upgrade to Python 3.10 or newer, or stick to `pillow-heif` versions prior to `1.2.0`.","severity":"breaking","affected_versions":"<1.2.0"},{"fix":"For AVIF, use Pillow's native support (Pillow>=9.1.0) or downgrade `pillow-heif` to `<1.0.0`.","message":"AVIF support was deprecated in `v0.22.0` and completely dropped in `v1.0.0`. This was done because Pillow itself gained native AVIF support. If you rely on `pillow-heif` for AVIF, you must either use an older version or transition to Pillow's native AVIF capabilities.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Upgrade to `pillow-heif>=1.3.0` immediately to patch the vulnerability.","message":"Versions prior to `1.3.0` are vulnerable to an integer overflow in the encode path buffer validation, which could lead to heap out-of-bounds read (CVE-2026-28231, GHSA-5gjj-6r7v-ph3x). This is a critical security vulnerability.","severity":"breaking","affected_versions":"<1.3.0"},{"fix":"Ensure `pillow_heif.options.PREFERRED_DECODER` is set to an ID returned by `pillow_heif.libheif_info().decoder_ids` if used.","message":"As of `v1.2.0`, the `PREFERRED_DECODER` option must always specify a valid and available decoder ID, otherwise an exception will be raised. Previously, an invalid decoder might have been silently ignored.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Upgrade to `pillow-heif>=1.2.1` if you are using `opencv-python` on macOS.","message":"On macOS, versions prior to `1.2.1` could crash when `opencv-python` (`cv2`) and `pillow-heif` were both used, due to conflicts in bundled `libx265` libraries. This issue was fixed in `v1.2.1`.","severity":"gotcha","affected_versions":"<1.2.1"}],"env_vars":null,"search_vec":"'1.3.0':39 'activ':45 'bug':55 'bundl':52 'cadenc':47 'current':36 'effici':28 'enabl':15 'file':30 'fix':56 'fork':19 'format':31 'frequent':49 'heic':33,60 'heif':3,6,26,59 'high':27 'imag':20,29,34,57 'interfac':10 'libheif':13,63 'librari':14,21,53 'maintain':43 'open':23 'pil':18,62 'pillow':2,5,17,61 'pillow-heif':1,4 'process':58 'project':42 'python':9 'releas':46 'save':25 'updat':50 'version':37","created_at":"2026-04-09T03:56:06.979927+00:00","updated_at":"2026-04-16T18:01:03.224723+00:00","problems":[{"fix":"On Ubuntu/Debian, install `libheif-dev` using `sudo apt update && sudo apt install -y libheif-dev`. On macOS with Homebrew, run `brew install libheif`. For Windows, it's recommended to use prebuilt binaries by simply running `pip install pillow-heif` which usually fetches a wheel. If building from source is necessary on Windows, install MSYS2 and related libraries as per the official documentation.","cause":"The `pillow-heif` library requires system-level development headers for `libheif` and its dependencies (like `x265`, `aom`, `libde265`) to be installed for successful compilation, which `pip` cannot automatically manage.","error":"Failed building wheel for pillow-heif"},{"fix":"Before opening HEIC files with `PIL.Image.open()`, you must import and call `register_heif_opener()` from `pillow_heif` once in your application. \n```python\nfrom PIL import Image\nfrom pillow_heif import register_heif_opener\n\nregister_heif_opener()\n\nimage = Image.open('image.heic')\n```","cause":"Pillow does not natively support HEIC/HEIF formats. The `pillow-heif` library provides this support as a plugin, which must be explicitly registered with Pillow.","error":"PIL.UnidentifiedImageError: cannot identify image file 'path/to/image.heic'"},{"fix":"Remove any calls to `pillow_heif.register_avif_opener()`. If you need to open AVIF files, ensure your Pillow version is recent enough (Pillow 9.1.0 or later for native AVIF support). If you specifically require the `pillow-heif` AVIF functionality, you may need to downgrade `pillow-heif` to a version prior to 1.0.0 (e.g., `pip install pillow-heif<1.0`).","cause":"Starting with `pillow-heif` version 1.0.0, support for AVIF images was removed from this library because Pillow itself gained native AVIF support, making the `register_avif_opener` function obsolete.","error":"AttributeError: module 'pillow_heif' has no attribute 'register_avif_opener'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.5.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/bigcat88/pillow_heif","docs":"https://pillow-heif.readthedocs.io","changelog":"https://github.com/bigcat88/pillow_heif/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/pillow-heif/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":null}}