{"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":"en","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,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}