Registry / data / pi-heif

pi-heif

JSON →
library1.4.0pypypi✓ verified 23d ago

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.

pip install pi-heif
INSTALL
IMPORT
SIG · PI-HEIF
P
pi-heif
datapythonv1.4.0
Install
2.3s avg
Import
136ms
Disk
41MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✓ —
✓ 2.4s
py 3.11
✓ —
✓ 2.3s
py 3.12
✓ —
✓ 2s
py 3.13
✓ —
✓ 2.3s
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.
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.
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.
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.
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.
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()`.
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.
fix
Upgrade 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.
fix
Upgrade 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.
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.
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()`.
Agent activity
14 hits · last 30 days
node
12
Resources
pi-heif — pip install pi-heif · libregistry