Installation — pillow-heif 1.6.0 documentation

# Installation

## Basic Installation

Note

This is a recommended way of installation for use.

Install Pillow-Heif with pip:

    python3 -m pip install --upgrade pip
    python3 -m pip install --upgrade pillow-heif

Wheels are present for most popular systems with help of cibuildwheel

## Building From Source

### Linux

Note

Here is the build script used to build `libheif` with its encoders and decoders for the wheels.
Extra `cmake` arguments for the `libheif` build can be passed with the `PH_LIBHEIF_CMAKE_ARGS` environment variable, they override the default ones, e.g. `PH_LIBHEIF_CMAKE_ARGS="-DWITH_KVAZAAR=ON" python3 libheif/build_libs.py`
And of course you can build your own libheif library with your preferred encoders and decoders and use what you like.

There is many different ways how to build it from source. Main requirements are:

  - `libheif` should be version >= `1.23.1`.

  - `x265` should support 10 - 12 bit encoding(if you want to save in that bitness)

  - `aom` should be >= `3.3.0` version

  - `libde265` should be >= `1.0.8` version

Distro packages are too old: even the `strukturag` PPA tops out at `libheif` `1.19.x`, so build `libheif` from source first, e.g. with the build script from the source tree:

On Ubuntu:

`sudo apt update`
`sudo apt -y install cmake nasm build-essential curl`
`sudo python3 libheif/build_libs.py`

On Alpine:

`sudo apk add --no-cache cmake nasm build-base curl`
`sudo python3 libheif/build_libs.py`

Now install Pillow-Heif with:

    python3 -m pip install --upgrade pillow-heif --no-binary :all:

or from within the uncompressed source directory:

    python3 -m pip install .

Note

Refer to libheif repo for additional information of how to build it with what features you want.

If you have questions about build from sources you can ask them in discussions or create an issue.

### FreeBSD

Action to test build on FreeBSD from source

Since Python itself does not support binary wheels for BSD systems, you should install libheif and then simply install Pillow-Heif from source.

Install gcc, cmake, aom and x265:

    - pkg install -y gcc cmake aom x265
    - pkg install -y py39-pip
    - pkg install -y py39-pillow py39-numpy
    - python3 libheif/build_libs.py

Install Python and Pillow:

    pkg install -y py39-pip
    pkg install -y py39-pillow

Install Pillow-Heif:

    python3 -m pip install .

### macOS

First install Homebrew, if it is not installed and run:

    brew install x265 libjpeg libde265 libheif
    python3 -m pip install --upgrade pip

Now install Pillow-Heif with:

    python3 -m pip install --upgrade pillow-heif --no-binary :all:

or from within the uncompressed source directory:

    python3 -m pip install .

### Windows

Note

On Windows, use prebuilt binaries. Installing from source on Windows is tricky.
First install msys2, if it is not installed.
By default, build script assumes that msys2 builds libs in `C:/msys64/mingw64`
You can set MSYS2_PREFIX environment variable to your custom path, e.g.:
`setx MSYS2_PREFIX "D:/msys64/mingw64"`

Using msys2 terminal change working directory and install libheif:

    cd .../pillow_heif/libheif/windows/mingw-w64-libheif
    makepkg-mingw --syncdeps
    pacman -U mingw-w64-x86_64-libheif-*-any.pkg.tar.zst

Note

This is needed, so we dont want to dav1d, rav1e or libSvtAv1Enc to be installed as the dependencies.

Now inside Pillow-Heif directory install it with pip from source:

    python -m pip install .

After that copy libheif.dll, libaom.dll, libde265-0.dll, libx265.dll, libgcc_s_seh-1.dll, libstdc++-6.dll and libwinpthread-1.dll from msys64\mingw64\bin to python site-packages root.