Installation
============

Basic Installation
------------------

.. note::

    This is a recommended way of installation for use.

Install Pillow-Heif with :command:`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 <https://cibuildwheel.readthedocs.io/en/stable/>`_

Building From Source
--------------------

.. role:: bash(code)
   :language: bash

Linux
^^^^^

.. note::

    | Here is the
        `build script <https://github.com/bigcat88/pillow_heif/blob/master/libheif/build_libs.py>`_
        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`:

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

On `Alpine`:

| :bash:`sudo apk add --no-cache cmake nasm build-base curl`
| :bash:`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 <https://github.com/strukturag/libheif>`_ 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 <https://github.com/bigcat88/pillow_heif/blob/master/ci/cirrus_general_ci.yml>`_

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 <https://brew.sh>`_, 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 <https://www.msys2.org/>`_, if it is not installed.
    | By default, build script assumes that **msys2** builds libs in :bash:`C:/msys64/mingw64`
    | You can set **MSYS2_PREFIX** environment variable to your custom path, e.g.:
    | :bash:`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.
