Skip to main content

Python 3.6+ interface to libheif library

Project description


Python 3.6+ interface to libheif library using CFFI

Note: currently only reading is supported.


Simple installation - Linux (installs manylinux2014 wheel, doesn't work with Alpine)

pip install pyheif

Installing from source - MacOS

brew install libffi libheif
pip install git+

Installing from source - Linux

apt install libffi libheif-dev libde265-dev


yum install libffi libheif-devel libde265-devel


pip install git+

Installing from source - Windows

Sorry, not going to happen!


The function can be used to read a HEIF encoded file. It can be passed any of the following:

  • A string path to a file on disk
  • A pathlib.Path path object
  • A Python bytes or bytearray object containing HEIF content
  • A file-like object with a .read() method that returns bytes

It returns a HeifFile object.

import pyheif

# Using a file path:
heif_file ="IMG_7424.HEIC")
# Or using bytes directly:
heif_file ="IMG_7424.HEIC", "rb").read())

The HeifFile object

The returned HeifFile has the following properties:

  • mode - the image mode, e.g. "RGB" or "RGBA"
  • size - the size of the image as a (width, height) tuple of integers
  • data - the raw decoded file data, as bytes
  • metadata - a list of metadata dictionaries
  • color_profile - a color profile dictionary
  • stride - the number of bytes in a row of decoded file data
  • bit_depth - the number of bits in each component of a pixel

Converting to a Pillow Image object

If your HEIF file contains an image that you would like to manipulate, you can do so using the Pillow Python library. You can convert a HeifFile to a Pillow image like so:

from PIL import Image
import pyheif

heif_file ="IMG_7424.HEIC")
image = Image.frombytes(

Note: the mode property is passed twice - once to the mode argument of the frombytes method, and again to the mode argument of the raw decoder.

You can now use any Pillow method to manipulate the file. Here's how to convert it to JPEG:"IMG_7424.jpg", "JPEG")

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyheif-0.5.1.tar.gz (17.9 kB view hashes)

Uploaded source

Built Distributions

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page