# What changed in pillow-heif

> 16 changes in pillow-heif 1 from its official release notes, upgrade guides and advisories: 3 breaking, 2 security, 4 new APIs and options. Each one cited. Sources checked 2026-10-27. HTML: https://unstale.sh/pypi/pillow-heif/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## pillow-heif 1

### Breaking changes

- Version 1.8.1 is the last version supporting Python 3.10 and Pillow 11/12; version 1.9.0 will require Pillow 13 and Python 3.11 or newer. (1.8.1) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.1)
- Saving ;10 or ;12 data with sample values above its bit depth now raises ValueError. (1.8.1) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.1)
- The minimum required libheif version is now 1.23.4. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)

### Security

- Fixes an out-of-bounds read when stride is smaller than the image row width. (1.7.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.7.0)
- pillow-heif: Integer Overflow in Encode Path Buffer Validation Leads to Heap Out-of-Bounds Read (1.3.0) — [security advisory](https://github.com/advisories/GHSA-5GJJ-6R7V-PH3X)

### New APIs and options

- Adds draft support in the Pillow plugin for decoding embedded thumbnails. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- The info dictionary can include entity_groups to identify which images form a stereo pair in spatial photos. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- Adds a method for decoding embedded thumbnails. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- The info dictionary supports reading and writing nominal diffuse white luminance HDR metadata with this key. (1.7.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.7.0)

### Performance

- Uses embedded thumbnails instead of decoding the full image. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)

### Tooling

- The marker makes the package's type annotations visible to type checkers. (1.7.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.7.0)

### Fixes and other changes

- Opening a file with a metadata item type that is not valid UTF-8 no longer causes a segmentation fault. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- Loading a multi-frame image no longer reloads frame data on every call, discards in-place changes, or fails after thumbnail(). (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- Names imported from pillow_heif are recognized as exported by type checkers, restoring strict mypy checks and Pyright/Pylance autocompletion. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- Depth images with an item type libheif cannot decode are skipped instead of making the whole file unreadable. (1.8.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.8.0)
- Saving an image no longer raises a TypeError when its info dictionary contains non-string keys. (1.7.0) — [release notes](https://github.com/bigcat88/pillow_heif/releases/tag/v1.7.0)