{"id":2663,"library":"pi-heif","title":"Pillow-HEIF","description":"Pillow-HEIF (pi-heif) provides a robust Python interface for the libheif library, enabling reading and writing of HEIF/HEIC image files. It integrates seamlessly with the popular Pillow imaging library, extending its capabilities to support the HEIF format. The library is actively maintained, with version 1.3.0 being the latest, and releases are frequent.","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","multimedia"],"install":[{"cmd":"pip install pi-heif","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Commonly used for image manipulation; `pi-heif` integrates with Pillow to enable HEIF/HEIC support for `PIL.Image.open()`.","package":"Pillow","optional":true}],"imports":[{"note":"Registers HEIF/HEIC support with Pillow, allowing `PIL.Image.open()` to handle HEIF files.","symbol":"register_heif_opener","correct":"from pillow_heif import register_heif_opener"},{"note":"Provides direct access to HEIF image objects for more granular control.","symbol":"HeifImage","correct":"from pillow_heif import HeifImage"}],"quickstart":{"code":"import os\nfrom PIL import Image\nfrom pillow_heif import register_heif_opener\n\n# Register HEIF/HEIC support with Pillow\nregister_heif_opener()\n\ndummy_heic_path = \"dummy.heic\"\noutput_jpeg_path = \"output.jpg\"\n\ntry:\n    # Create a dummy image using Pillow\n    img = Image.new(\"RGB\", (200, 150), color='blue')\n    print(f\"Created a dummy Pillow image of size {img.size}\")\n\n    # Save the dummy image as HEIF/HEIC using the registered opener\n    # Note: HEIF encoding might require libheif to be compiled with specific encoders\n    # If save fails, ensure libheif has an encoder available.\n    img.save(dummy_heic_path, format=\"HEIF\", quality=80)\n    print(f\"Saved dummy image to {dummy_heic_path} as HEIF.\")\n\n    # Open the HEIF/HEIC file using Pillow's Image.open()\n    with Image.open(dummy_heic_path) as heic_img:\n        print(f\"Successfully opened HEIC image: Format={heic_img.format}, Mode={heic_img.mode}, Size={heic_img.size}\")\n        \n        # Save it as JPEG\n        heic_img.save(output_jpeg_path)\n        print(f\"Saved HEIC image to {output_jpeg_path} as JPEG.\")\n\nexcept Exception as e:\n    print(f\"An error occurred during quickstart: {e}\")\n    print(\"This might be due to missing underlying libheif encoders/decoders, or unsupported system configuration.\")\nfinally:\n    # Clean up created files\n    if os.path.exists(dummy_heic_path):\n        os.remove(dummy_heic_path)\n        print(f\"Cleaned up {dummy_heic_path}\")\n    if os.path.exists(output_jpeg_path):\n        os.remove(output_jpeg_path)\n        print(f\"Cleaned up {output_jpeg_path}\")","lang":"python","description":"This quickstart demonstrates how to register `pillow_heif` with Pillow, create a dummy image, save it in HEIF/HEIC format, and then open and convert it to JPEG. This showcases the library's ability to extend Pillow's image handling."},"warnings":[{"fix":"Ensure your Python environment is 3.10 or newer for `v1.2.0+` (or 3.9+ for `v0.20.0` to `v1.1.x`). Upgrade your Python version or pin `pi-heif` to an older compatible version.","message":"Python 3.9 support was dropped in `v1.2.0`, and Python 3.8 support was dropped in `v0.20.0`. Attempting to install or use these versions on older Python interpreters will fail or lead to errors.","severity":"breaking","affected_versions":">=1.2.0 for Python 3.9; >=0.20.0 for Python 3.8"},{"fix":"For AVIF support, rely on Pillow's native AVIF capabilities by ensuring your Pillow version is recent enough. `pi-heif` no longer handles AVIF.","message":"AVIF format support was deprecated in `v0.22.0` and fully removed in `v1.0.0` due to Pillow gaining native AVIF capabilities. Attempting to open/save AVIF files via `pi-heif` will no longer work.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Before setting `PREFERRED_DECODER`, verify the decoder ID is valid and supported by the underlying `libheif` instance. Consult `libheif` documentation or available decoders via `HeifImage.get_supported_decoders()`.","message":"From `v1.2.0`, the `PREFERRED_DECODER` option must always specify a valid and available decoder ID. If not, an exception will be raised, whereas previously it might have silently failed or ignored an invalid setting.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"Upgrade to `v1.3.0` or a newer version immediately to mitigate this security risk, especially when processing untrusted HEIF files.","message":"A critical integer overflow vulnerability (CVE-2026-28231, GHSA-5gjj-6r7v-ph3x) affecting buffer validation was fixed in `v1.3.0`. This could lead to heap out-of-bounds reads during encoding, potentially allowing arbitrary code execution.","severity":"gotcha","affected_versions":"<1.3.0"},{"fix":"Upgrade to `v1.2.1` or a newer version to resolve the conflict and prevent crashes on macOS systems.","message":"On macOS, versions prior to `v1.2.1` could experience crashes when `cv2` (OpenCV Python bindings) and `pillow_heif` were both installed, due to conflicts in bundled `libx265` libraries. This was particularly problematic for users utilizing both image processing libraries.","severity":"gotcha","affected_versions":"<1.2.1 on macOS"},{"fix":"If encountering errors with large HEIF images, set `pillow_heif.options.DISABLE_SECURITY_LIMITS = True`. Be aware that disabling limits might increase memory usage or expose to other vulnerabilities if processing malicious files.","message":"The `pillow_heif.options.DISABLE_SECURITY_LIMITS` boolean was introduced in `v0.22.0` to bypass `libheif`'s internal security limits on image sizes, which might be necessary for very large files. Disabling this can lead to high memory usage.","severity":"gotcha","affected_versions":">=0.22.0"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}