Install & Compatibility
Where this runs
tested against v1.4.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
py 3.9
✕ build_error
✕ build_error
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
HeifFile
✓ from pi_heif import HeifFile
✗ from pillow_heif import register_heif_opener
from_bytes
✓ from pi_heif import from_bytes
from_pillow
✓ from pi_heif import from_pillow
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.
import os
from PIL import Image
from pillow_heif import register_heif_opener
# Register HEIF/HEIC support with Pillow
register_heif_opener()
dummy_heic_path = "dummy.heic"
output_jpeg_path = "output.jpg"
try:
# Create a dummy image using Pillow
img = Image.new("RGB", (200, 150), color='blue')
print(f"Created a dummy Pillow image of size {img.size}")
# Save the dummy image as HEIF/HEIC using the registered opener
# Note: HEIF encoding might require libheif to be compiled with specific encoders
# If save fails, ensure libheif has an encoder available.
img.save(dummy_heic_path, format="HEIF", quality=80)
print(f"Saved dummy image to {dummy_heic_path} as HEIF.")
# Open the HEIF/HEIC file using Pillow's Image.open()
with Image.open(dummy_heic_path) as heic_img:
print(f"Successfully opened HEIC image: Format={heic_img.format}, Mode={heic_img.mode}, Size={heic_img.size}")
# Save it as JPEG
heic_img.save(output_jpeg_path)
print(f"Saved HEIC image to {output_jpeg_path} as JPEG.")
except Exception as e:
print(f"An error occurred during quickstart: {e}")
print("This might be due to missing underlying libheif encoders/decoders, or unsupported system configuration.")
finally:
# Clean up created files
if os.path.exists(dummy_heic_path):
os.remove(dummy_heic_path)
print(f"Cleaned up {dummy_heic_path}")
if os.path.exists(output_jpeg_path):
os.remove(output_jpeg_path)
print(f"Cleaned up {output_jpeg_path}")
Debug
Known issues
breakingPython 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.fixEnsure 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.
affects: >=1.2.0 for Python 3.9; >=0.20.0 for Python 3.8
breakingAVIF 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.fixFor AVIF support, rely on Pillow's native AVIF capabilities by ensuring your Pillow version is recent enough. `pi-heif` no longer handles AVIF.
affects: >=1.0.0
gotchaFrom `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.fixBefore 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()`.
affects: >=1.2.0
gotchaA 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.fixUpgrade to `v1.3.0` or a newer version immediately to mitigate this security risk, especially when processing untrusted HEIF files.
affects: <1.3.0
gotchaOn 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.fixUpgrade to `v1.2.1` or a newer version to resolve the conflict and prevent crashes on macOS systems.
affects: <1.2.1 on macOS
gotchaThe `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.fixIf 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.
affects: >=0.22.0
Upgrade
Version history
1.4.0latest on PyPI · released Jun 10, 2026
Audit
Dependencies
PillowoptionalCommonly used for image manipulation; `pi-heif` integrates with Pillow to enable HEIF/HEIC support for `PIL.Image.open()`.