Pillow-HEIF

Python interface for libheif library providing comprehensive HEIF/AVIF image processing with both standalone library and Pillow plugin capabilities. Supports 8/10/12-bit images, full metadata handling (EXIF/XMP/IPTC), multi-image files, thumbnails, depth images, and auxiliary images.

Package Information

• Package Name: pillow-heif
• Language: Python
• Installation: pip install pillow-heif
• Python Version: 3.9 - 3.13

Core Imports

import pillow_heif

For Pillow plugin integration:

from pillow_heif import register_heif_opener
register_heif_opener()

Basic Usage

Standalone Library Usage

import pillow_heif

# Check if file is supported
if pillow_heif.is_supported("image.heic"):
    # Open HEIF file
    heif_file = pillow_heif.open_heif("image.heic")
    
    # Access image properties
    print(f"Size: {heif_file.size}")
    print(f"Mode: {heif_file.mode}")
    print(f"Has alpha: {heif_file.has_alpha}")
    
    # Convert to Pillow Image
    pil_image = heif_file.to_pillow()
    
    # Save as HEIF
    heif_file.save("output.heic", quality=90)

Pillow Plugin Usage

from PIL import Image
from pillow_heif import register_heif_opener

# Register HEIF support with Pillow
register_heif_opener()

# Use Pillow normally with HEIF support
im = Image.open("image.heic")
im = im.rotate(13)
im.save("rotated_image.heic", quality=90)

Architecture

Pillow-HEIF provides two main usage modes:

• Standalone Library: Direct access to HEIF/AVIF functionality through HeifFile and HeifImage classes
• Pillow Plugin: Seamless integration with PIL/Pillow, adding HEIF support to existing workflows

The library is built around several core concepts:

• HeifFile: Container for one or more HEIF/AVIF images with metadata
• HeifImage: Individual images within a file with processing capabilities
• Auxiliary Images: Additional data like depth maps, thumbnails, alpha masks
• Metadata Support: Complete EXIF, XMP, and IPTC handling
• Multi-format Support: Both HEIF and AVIF with various bit depths (8/10/12-bit)

Capabilities

File Operations

Core functionality for opening, reading, and validating HEIF/AVIF files. Includes support for format detection, multi-image files, and various opening modes.

def open_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) -> HeifFile: ...
def read_heif(fp, convert_hdr_to_8bit=True, bgr_mode=False, **kwargs) -> HeifFile: ...
def is_supported(fp) -> bool: ...

File Operations

Image Classes

Main container and image classes for handling HEIF/AVIF data, including primary images, depth images, and auxiliary images with comprehensive metadata access.

class HeifFile: ...
class HeifImage: ...
class HeifDepthImage: ...
class HeifAuxImage: ...

Image Classes

Encoding

Functions for creating HEIF/AVIF files from raw data, Pillow images, or other sources with extensive encoding options and quality control.

def encode(mode, size, data, fp, **kwargs): ...
def from_pillow(pil_image) -> HeifFile: ...
def from_bytes(mode, size, data, **kwargs) -> HeifFile: ...

Encoding

Pillow Integration

Plugin functionality that adds seamless HEIF/AVIF support to Pillow, including the HeifImageFile class and registration functions.

def register_heif_opener(**kwargs): ...
class HeifImageFile: ...

Pillow Integration

Metadata and Utilities

Helper functions for MIME type detection, orientation handling, library information, and plugin loading for extended format support.

def get_file_mimetype(fp) -> str: ...
def set_orientation(info) -> int | None: ...
def libheif_version() -> str: ...
def libheif_info() -> dict: ...

Metadata and Utilities

Configuration Options

Runtime configuration variables that control library behavior:

# Available in pillow_heif.options module
DECODE_THREADS = 4  # Threading for decoding
THUMBNAILS = True  # Enable thumbnail support
DEPTH_IMAGES = True  # Enable depth image support
AUX_IMAGES = True  # Enable auxiliary image support
QUALITY = None  # Default encoding quality
SAVE_HDR_TO_12_BIT = False  # HDR bit depth preference
SAVE_NCLX_PROFILE = True  # Color profile handling
PREFERRED_ENCODER = {"AVIF": "", "HEIF": ""}  # Encoder preferences
PREFERRED_DECODER = {"AVIF": "", "HEIF": ""}  # Decoder preferences

Color Space and Metadata Types

# Enum types for color space handling
class HeifColorPrimaries(IntEnum): ...
class HeifTransferCharacteristics(IntEnum): ...
class HeifMatrixCoefficients(IntEnum): ...
class HeifDepthRepresentationType(IntEnum): ...

Error Handling

The library handles various error conditions gracefully:

• Unsupported files: Use is_supported() to check before opening
• Corrupted data: IOError or specific libheif exceptions raised
• Missing dependencies: Import errors for optional features
• Memory limits: Configurable security limits via DISABLE_SECURITY_LIMITS