NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #842 most downloaded on PyPI
Python interface for libheif library
Last release 13 days ago
22 Sep 2026
Ships fairly regularly
a new release about every 6 weeks
Nearly every release is documented
notes for 49 of 49 stable releases
Nothing withdrawn
no release was ever pulled
5 years old
49 releases · first in 2021
One column per quarter.
Reading of entity groups: entity_groups key in info dictionary, tells which images form a stereo pair in spatial photos. #476
entity_groups key in info dictionary, tells which images form a stereo pair in spatial photos. #476HeifImage.get_thumbnail method and draft in the Pillow plugin, Image.thumbnail() uses them instead of decoding the full image. #477libheif version is 1.23.4. #480libheif was updated from the 1.23.3 to 1.23.4 version. #479libde265 was updated from the 1.1.2 to 1.1.3 version. #483load() of a multi-frame image reloaded the frame data on every call, discarding in-place changes and failing after thumbnail(). #477libheif cannot decode made the whole file unreadable with libheif 1.23.4, such depth images are now skipped. #480pillow_heif as private since the py.typed marker was added in 1.7.0: Pyright/Pylance and mypy --strict reported them as not exported, Pyright/Pylance autocompletion did not offer them. #490 Thanks to @BetoFernandez123Reading and writing nominal diffuse white luminance HDR metadata: nominal_diffuse_white_luminance key in info dictionary. #468
nominal_diffuse_white_luminance key in info dictionary. #468py.typed marker, the package type annotations are now visible to type checkers. #475libheif was updated from the 1.23.2 to 1.23.3 version. #470libde265 was updated from the 1.1.1 to 1.1.2 version. #471encode() when stride was smaller than the image row width. (GHSA-ccw6-q225-c975) Thanks to @arpitjain099 for finding this!TypeError when saving an image whose info dictionary contains non-string keys. #475Reading and writing HDR metadata: content_light_level , mastering_display_colour_volume , ambient_viewing_environment keys in info dictionary. #456
content_light_level, mastering_display_colour_volume, ambient_viewing_environment keys in info dictionary. #4563.15 and 3.15t wheels added.libheif was updated from the 1.23.1 to 1.23.2 version. #466data memoryview outlived the HeifFile it was created from. #453GPLv2 classifier, the package license is BSD-3-Clause; bundled library licenses in wheels are described in LICENSES_bundled.txt, which was updated to match the current libraries. #455Grid(tiled) image encoding: options.GRID_TILE_SIZE option, tile_size parameter for save and grid_tile_size parameter for register_*_opener . #317
options.GRID_TILE_SIZE option, tile_size parameter for save and grid_tile_size parameter for register_*_opener. #317info["tiling"] dictionary with the grid info for tiled images. #317PH_LIBHEIF_CMAKE_ARGS environment variable for build_libs.py to pass extra cmake arguments to the libheif build.libheif version is 1.23.1.libheif was updated from the 1.23.0 to 1.23.1 version. #445libde265 was updated from the 1.1.0 to 1.1.1 version. #434libheif was updated from the 1.21.2 to 1.23.0 version. #426
libheif was updated from the 1.21.2 to 1.23.0 version. #426libde265 was updated from the 1.0.16 to 1.1.0 version. #426libx265 was updated from the 4.1 to 4.2 version. #426libheif version is 1.19.0. #416options.ALLOW_INCORRECT_HEADERS option. Starting with libheif 1.22.0, libheif itself rejects images whose decoded size does not match the ispe header. #426sRGB NCLX color profile (BT.709 primaries) is now written by default during encoding when no color information was provided, to avoid color shifts in viewers. #407Integer overflow in encode path buffer validation leading to heap out-of-bounds read. ( CVE-2026-28231 , GHSA-5gjj-6r7v-ph3x ) Thanks to @kaizawa97 fo…
macOS: crash when cv2 and pillow_heif both bundle libx265 #403
cv2 and pillow_heif both bundle libx265 #403libheif was updated from the 1.20.2 to 1.21.2 version. #399
1.20.2 to 1.21.2 version. #399Python 3.9 support. #402PREFERRED_DECODER must now always be a valid, available decoder ID, or an exception will be raised. (libheif change)libheif was updated from the 1.20.1 to 1.20.2 version.
libheif was updated from the 1.19.8 to 1.20.1 version.
3.14 wheels added.libheif was updated from the 1.19.8 to 1.20.1 version.x265 was updated to the 4.1 version for Linux build to be in sync with macOS and Windows.Removed deprecated PyPy 3.9 wheels & added PyPy 3.11 wheels.
AVIF format marked as deprecated and pending for the removal.
pillow_heif.options.DISABLE_SECURITY_LIMITS to bypass security limit of libheif for the image size. #328libx265 library was updated to the latest 4.1 version.libheif was updated from the 1.19.5 to 1.19.7 version.AVIF format marked as deprecated and pending for the removal.Error argument '-Ofast' is deprecated when building from source. #305
1.18.2 to 1.19.5 version. #312x86_64), the minimum supported version for binary wheels has been raised from 12 to 13.argument '-Ofast' is deprecated when building from source. #305Initial support for parsing auxiliary images. #297 Thanks to @johncf
1.18.1 to 1.18.2 version. #278Python 3.8 support. #293C module. #298 Thanks to @johncfPillow 11.0.0 #294image.info["heif"] dictionary with camera_intrinsic_matrix HEIF specific metadata. Currently only reading is supported. #271
image.info["heif"] dictionary with camera_intrinsic_matrix HEIF specific metadata. Currently only reading is supported. #2711.17.6 to 1.18.1 version. #2493.13.0b3 wheels added; macOS arm64 Python3.8 wheels dropped. #272Minimum supported Pillow version raised to 10.1.0. #251
Pillow 10.4.0 #25410.1.0. #251xmp in info dictionary is now not present if it is empty. #254P mode with transparency = 0. #238This release contains breaking change for monochrome images.
This release contains breaking change for monochrome images.
L or I;16 mode instead of RGB. #215convert_hdr_to_8bit value now ignores monochrome images. #215subsampling parameter for encoding has higher priority than chroma. #213libehif version is 1.17.0. #2149.5.0. #216libheif_info function: added encoders and decoders keys to the result, for future libheif plugins support. #189
libheif_info function: added encoders and decoders keys to the result, for future libheif plugins support. #189options.PREFERRED_ENCODER - to use encoder different from the default one. #192options.PREFERRED_DECODER - to use decoder different from the default one. #193Synonym for chroma encoder parameter: subsampling(usage is the same as in Pillow JPEG). #161 #165
chroma encoder parameter: subsampling(usage is the same as in Pillow JPEG). #161 #165image_orientation value to libheif, instead of manually rotating image according to EXIF before encoding. #168YCbCr mode for saving without converting to RGB. #169armv7 wheels. #1601.14.1.libheif and other libraries are no longer try built automatically. #1581.16.2 to 1.17.5 version. #166 #175NCLX color profile - was reworked, updated docs, see PR for more info. #1719.2.0.cmake>=3.16.3 dropped Debian 10 armv7 wheels. #1601.0.12 to 1.0.14. changelog1.17.x. #156Linux: libaom updated to 3.6.1, musllinux builds switched to musllinux_1_2 tag.
PyPy 3.8 wheels.libaom updated to 3.6.1, musllinux builds switched to musllinux_1_2 tag.libheif using pkg-config. #128Depth Image read support, they are available as a list in im.info["depth_images"] #116
Python 3.12, PyPy 3.10 wheels.Depth Image read support, they are available as a list in im.info["depth_images"] #116options.SAVE_NCLX_PROFILE - default False to be full compatible with previous versions, but in next versions may be changed to True. #118 Thanks to @wiggin15Pillow 10.1.0Pillow version increased from 8.4.0 to 9.1.1Python 3.7 support, PyPy 3.8 wheels.Pillow-Heif. Pi-Heif still have 32-bit wheels.This release is fully compatible with previous versions.
This release is fully compatible with previous versions.
0.9.x versions to open HDR images in 10/12 bit. #96libde265(HEIF decoder) updated from 1.0.11 to 1.0.12 version. changeloglibheif updated to 1.16.2.apt-repository ppa:strukturag/libheifencode function with stride argument correctly saves image.from_bytes function with stride argument respect stride value during save.from_bytes function with stride argument can correctly translate to numpy array.This release is fully compatible with 0.10.x versions.
This release is fully compatible with 0.10.x versions.
0.11.0 - raw data again can begin with Exif\x00\x00. Thanks to @fabbaum #93deepcopy support for HeifFile class.Faster image loading implementation with Pillow 9.5.0
9.5.0options.ALLOW_INCORRECT_HEADERS option to allow loading files with invalid ispe header. Thanks to @Soooda #86libheif updated from 1.14.2 to 1.15.2Reworked version with native C extension.
Reworked version with native C extension.
LA modelibde265(HEIF decoder) updated from 1.0.9 to 1.0.11 version. changelogconvert_to method was removed, bgr_mode opt. parameter added to open_heifTwo bugs in XMP metadata handling that were causing exceptions. All versions were affected. Thanks to @eeyrw for pointing out such a problem.
Two bugs in XMP metadata handling that were causing exceptions. All versions were affected. Thanks to @eeyrw for pointing out such a problem.
libheif updated from 1.14.0 to 1.14.2
1.14.0 to 1.14.2info["nclx_profile"] changed type from bytes(format of which was not described) to dict.
convert_to method: RGBa to RGB mode support was removed(last Pillow supports it). #67nclx color profile. #64Minimum supported version of libheif to build from source is 1.13.0
libheif to build from source is 1.13.0Pillow version increased from 6.2.0 to 8.3.0, getxmp is used from Pillow now. #55options() was reworked. Added new DECODE_THREADS option. #57save method to accept exif as PIL.Image.Exif class. #51autoconf, automake and pkg-config.Deprecated options().ctx_in_memory was removed(default behaviour do not change).
musllinux_1_2_armv7l tag.libheif updated to 1.14.0 versionenc_params for save as List[Tuple[str, str]] was removed, now it accepts only Dict.options().ctx_in_memory was removed(default behaviour do not change).options().strict was removed(default behaviour do not change).check, open, read, check_heif functions was removed.scale method marked as deprecated.enc_params for save can now be of type int or float and will be automatically converted to str.manylinux_2_28_armv7l tag.3x).musllinux_1_2_armv7l tag.libheif updated to 1.14.0 versionenc_params for save as List[Tuple[str, str]] was removed, now it accepts only Dict.options().ctx_in_memory was removed(default behaviour does not change).options().strict was removed(default behaviour does not change).check, open, read, check_heif functions was removed.scale method marked as deprecated. Will be removed in 0.9.0 version.enc_params for save can now be of type int or float and will be automatically converted to str.manylinux_2_28_armv7l tag.3x).(HeifImagePlugin) register proper mimetype for HEIF format. #47
mimetype for HEIF format. #47EXIF data is corrupted. #48EXIF that do not start with b'EXIF' (Pillow 9.3.0). #46options().strict option marked as deprecated and will be removed in 0.8.0.
premultiplied alpha channel (Pillow does not fully support these).premultiplied_alpha read-write property.to_pillow method to HeifFile class.RGBA;16 -> RGBA conversion.RGBa -> RGB conversion.libaom updated from 3.4.0 to 3.5.0 version. changeloglibde265 updated from 1.0.8 to 1.0.9.get_file_mimetype function has been reworked and is now written in python.is_supported function has been reworked and is now written in python.options().strict option marked as deprecated and will be removed in 0.8.0.check_heiffunction marked as deprecated.convert_to should do nothing if the target mode is already the current image mode..avifs files, libheif does not support them.CMYK mode will be converted for RGBA mode during saving instead of throwing KeyError exception.This release is fully compatible with previous versions.
This release is fully compatible with previous versions.
libheif updated to version 1.13.0Apache 2.0(Linux, Windows) libde265: CVE-2022-1253, CVE-2021-36408, CVE-2021-36410, CVE-2021-35452, CVE-2021-36411 MSYS2 PR
This release contains security and bug fixes.
420(which is a default mode) encoded images are closer to the originals with arrived patches. libheif issue21 patches with fixes from official libheif repo has arrived.This release is fully compatible with previous versions if you was not using AVIF decoding before.
This release is fully compatible with previous versions if you was not using AVIF decoding before.
save method accepts optional parameter format. If format="AVIF" output file will be encoded in h264 format using AOM.AvifImagePlugin introduced. Usage: register_avif_opener() or import pillow_heif.AvifImagePluginAvifImagePlugin you can work with .avif files the same way you do with .heic.avif files, register AvifImagePlugin if you need that. If you use pillow_avif then do not =)options().hevc_enc property was removed.options().avif property was removed.pillow_avif package.2x).enc_params for save changed type from List[Tuple[str, str]] to Dict. Old code will still work, but marked as deprecated.
This release is fully compatible with 0.5.0 version.
chroma=4xx optional subsampling parameter for save. Equivalent to enc_params=[("chroma", "4xx")] in old versions.enc_params for save changed type from List[Tuple[str, str]] to Dict. Old code will still work, but marked as deprecated.libheif_info now returns also bundled versions of x265 and aom.options().avif marked as deprecated. Starting from 0.6.0 version to register an AVIF plugin there will be a separate function and it will be disabled by default.options().hevc_enc marked as deprecated and will be removed in 0.6.0.1 and xmp orientation different from 1 present at same time.exiftool in some cases.libaom on Linux and Windows from 3.3.0 to 3.4.0 version. MacOS builds had already that version in 0.5.0.save methods for HEIF format if build does not contains HEIF encoder(for custom builds from source).Pillow plugin mode.Thumbnails was reworked, if you was not use them before, then this release is fully compatible with 0.4.0 version. It is a final API release, no more
Thumbnails was reworked, if you was not use them before, then this release is fully compatible with 0.4.0 version.
It is a final API release, no more further changes to existing API are planned, only bugfixes if any and etc.
thumbnail function, docs for it.__numpy_array__ property to HeifFileconvert_to method to HeifFilecp3x-abi3-xxx.whl), 3x less size on PyPi.to_pillow method, now fills metadata from an original image if was called for thumbnails.open current frame in multi frame images are set to index of Primary Image.add_thumbnails method moved from HeifFile/HeifImage to separate file and now can accept a PIL Image.speed up for reading images having thumbnails in a Pillow plugin mode.XMP metadata save from TIFF and JPEG.EXIF metadata save from TIFF(only for Pillow >= 9.2).(Heif) - Numpy array interface support.
add_from_bytes method and from_bytes function added. Allows to read 16-bit color images with OpenCV(or any other library) and save it as 10(12) bit HEIF.convert_to method to HeifImage to provide an easy way to open 10 or 12 bit images as 16 bit for OpenCV(or any other library)I, I;16, BGRA;16, BGR;16, BGRA, BGR modes.save_to_12bit to options, default False. Determines to what bitness will be converted 16 bit images during saving.10/12 bit images changed their byte order from Big Endian to Little Endian. Probably no one still use that API, but who knows...HeifFile.chroma and HeifFile.color properties was removed(they were not documented so probably no one will notice this), that info now stored in mode.mode for 10/12 bits was changed and accepts wider range of values, look hereupdated & rewritten to reflect all those changes.Examples were fixed & rewritten(were broken from 0.3.1+ versions).exif loading in HEIF sequence for Pillow 9.2+ (https://github.com/python-pillow/Pillow/pull/6335)Support of saving images with mode="1" in "L" mode.
"1" in "L" mode."L" are now saved natively in Monochrome mode(increase speed & decreased required memory and a bit less size) #26save append_images parameterSEGFAULT during encoding with some stride values.(Heif) - HeifFile gets images: List[HeifImage] and alternative method of changing order of images by editing it.
HeifFile gets images: List[HeifImage] and alternative method of changing order of images by editing it.info image dictionary can be now edited in place and it will be saved for image sequences.(HeifImagePlugin, Heif) - save now recognizes exif= and xmp= optional parameters. Works as in other Pillow plugins. #25
save now recognizes exif= and xmp= optional parameters. Works as in other Pillow plugins. #25save now recognizes primary_index optional parameter.info["primary"] value.primary_index method to HeifFile class.HeifFile points to primary image as it was before, but it can be not the first image in a list.Primary or not is to perform check of info["primary"] value.HeifImageThumbnail, added get_original method.save bug, when first frame was saved instead of current.(HeifImagePlugin) - support for PIL.ImageFile.LOAD_TRUNCATED_IMAGES flag.
PIL.ImageFile.LOAD_TRUNCATED_IMAGES flag.10 and 12 bit images. #24vcpkg build by MSYS2(MinGW) build, report of any possible bugs you see.(HeifImagePlugin) - saving of XMP tags from PNG.
ctx_in_memory, default=True. Benchmarks showed that versions 0.1.x which worked like that, was much faster.
This will not affect any user code, changes are internal.(HeifImagePlugin) - custom_mimetype field added like in other Pillow's plugins, instead of info["brand"]
custom_mimetype field added like in other Pillow's plugins, instead of info["brand"]mimetype field added to HeifFile class, instead of info["brand"]apply_transformations parameter in function open_heif was removed.brand and main values from info dictionary.original_bit_depth property. It will not break any existing code. See docs.reset_orientation was renamed to set_orientation.exif rotation, when converting from non heif to heif. See in docs chapter: Workaroundsappend_images parameter present.fp will be open after encoding process finished, and not before start.HeifImage.chroma and HeifImage.color property now available before the image load, right after open.(HeifImagePlugin, Heif) append_images parameter to save methods.
append_images parameter to save methods.import pillow_heif.HeifImagePlugin for automatic Pillow plugin registration(as alternative to calling register_heif_opener).quality can be now -1 which indicates a lossless encoding.getxmp method. Works the same way as in Pillow's PngImagePlugin | JpegImagePlugin.xml as info["xml"] and public function pillow_heif.getxmp(the same as for HeifImagePlugin)Memory Leak when Opening images, that appear in version 0.2.0 was Slain Like a Hydra (C)fp, this bug was only in 0.2.0+ versions.strides of thumbnails. More tests for that.Linux aarch64 PyPy 3.7 & 3.8 wheels.
get_file_mimetype.burst(container) image support(ImageSequence) for heic and hif when using as a pillow plugin.reader and plugin use.(Undecoded)``HeifFile class now support access images by index.heif_brand_* constants was removed, as mentioned in changes for 0.1.9 version.as_opener register image/heic mimetype in addition to image/heif.as_opener also registers .heif extension, thanks @dust-to-dust for pointing that.as_opener sets orientation tag to 1 from Exif to not rotate image twice(libheif already do transforms)reader you can do that manually if needed, with new reset_orientation function.macOS Intel PyPy3.7 & PyPy3.8 v7.3 wheels.
HeifCompressionFormat(IntEnum). have_decoder_for_format and have_encoder_for_format functions.libheif_info that returns dictionary with the version and available (en)(de)coders.HeifThumbnail for thumbnails, see in examples. Only for reader now, the next version will be for Pillow plugin as well.burst), see in examples. Only for reader now, the next version will be for Pillow plugin as well.thumbnails_all returning an iterator for getting thumbnails in all images in HeifFile.options function, that returns PyLibHeifOptions class with those properties.HEIF will try to get 16 bytes instead of 12.More auto tests before publishing.
Added libaom library to linux build.
First normal working release.
libaom library to linux build.as_opener function. Thanks for this to @DimonLavronYour coding agent can read these notes before it upgrades. Set up the MCP server →