libheif is a ISO/IEC 23008-12:2017 HEIF file format decoder and encoder.
Clone or download
Failed to load latest commit information.
examples adapt COPYING files to new example code license Oct 16, 2018
extra Include more files in release tarball. Jan 19, 2018
fuzzing Include new files in dist tarball. Jul 23, 2018
gnome Include GNOME / thumbnailer files in tarball and install to correct l… May 25, 2018
go go: Improve magics for format detection (based on #83). Sep 22, 2018
libheif Initialize a member of hdlf box. Oct 10, 2018
m4 Only expose public API through library. Jan 4, 2018
scripts Don't build Go code on CI tests that are cross compiling / fuzzing. Sep 21, 2018
.gitignore Also build Go example (if go binary is present). Sep 21, 2018
.travis.yml Integrate Coverity Scan in Travis. Sep 5, 2018
CMakeLists.txt fix base include directory in cmake May 25, 2018
COPYING adapt COPYING files to new example code license Oct 16, 2018
CPPLINT.cfg Add cpplint configuration (missing includes only for now). Jan 16, 2018 Include new files in dist tarball. Jul 23, 2018 change license of example programs in README (#87) Oct 15, 2018
appveyor.yml Fix version for AppVeyor. Aug 31, 2018 Install pre-commit hook to run cpplint. Jan 16, 2018 Don't build Go code when building with Emscripten. Sep 21, 2018 Add make target "format" to run "go fmt" on Go files. Sep 21, 2018 Modified the search order: directory first, then library Jun 9, 2018
post.js Don't expose internal API through Emscripten. Jun 14, 2018
pre.js Implement getting different images for Emscripten. Dec 15, 2017


Build Status Build Status Coverity Scan Build Status

libheif is an ISO/IEC 23008-12:2017 HEIF file format decoder and encoder.

HEIF is a new image file format employing HEVC (h.265) image coding for the best compression ratios currently possible.

libheif makes use of libde265 for the actual image decoding and x265 for encoding. Alternative codecs for, e.g., AVC and JPEG can be provided as plugins.

Supported features

libheif has support for decoding

  • tiled images
  • alpha channels
  • thumbnails
  • reading EXIF and XMP metadata
  • reading the depth channel
  • multiple images in an HEIF file
  • image transformations (crop, mirror, rotate)
  • overlay images
  • plugin interface to add decoders for additional formats (AVC, JPEG)
  • decoding of files while downloading (e.g. extract image size before file has been completely downloaded)

The encoder supports:

  • lossy compression with adjustable quality
  • lossless compression
  • alpha channels
  • thumbnails
  • save multiple images to an HEIF file
  • save EXIF and XMP metadata


The library has a C API for easy integration and wide language support. Note that the API is still work in progress and may still change.

Loading the primary image in an HEIF file is as easy as this:

heif_context* ctx = heif_context_alloc();
heif_context_read_from_file(ctx, input_filename, nullptr);

// get a handle to the primary image
heif_image_handle* handle;
heif_context_get_primary_image_handle(ctx, &handle);

// decode the image and convert colorspace to RGB, saved as 24bit interleaved
heif_image* img;
heif_decode_image(handle, &img, heif_colorspace_RGB, heif_chroma_interleaved_24bit, nullptr);

int stride;
const uint8_t* data = heif_pixel_image_get_plane_readonly(img, heif_channel_interleaved, &stride);

Writing an HEIF file can be done like this:

heif_context* ctx = heif_context_alloc();

// get the default encoder
heif_encoder* encoder;
heif_context_get_encoder_for_format(ctx, heif_compression_HEVC, &encoder);

// set the encoder parameters
heif_encoder_set_lossy_quality(encoder, 50);

// encode the image
heif_image* image; // code to fill in the image omitted in this example
heif_context_encode_image(ctx, nullptr, image, encoder);


heif_context_write_to_file(context, "output.heic");

See the header file heif.h for the complete C API.

There is also a C++ API which is a header-only wrapper to the C API. Hence, you can use the C++ API and still be binary compatible. Code using the C++ API is much less verbose than using the C API directly.

There is also an experimental Go API, but this is not stable yet.


This library uses a standard autoconf/automake build system. After downloading, run ./ to build the configuration scripts, then call ./configure and make. Make sure that you compile and install libde265 first, so that the configuration script will find this. Preferably, download the frame-parallel branch of libde265, as this uses a more recent API than version in the master branch. Also install x265 and its development files if you want to use HEIF encoding.

Compiling to JavaScript

libheif can also be compiled to JavaScript using emscripten. See the for further information.

Online demo

Check out this online demo. This is libheif running in JavaScript in your browser.

Example programs

Some example programs are provided in the examples directory. The program heif-convert converts all images stored in an HEIF file to JPEG or PNG. heif-enc lets you convert JPEG files to HEIF. The program heif-info is a simple, minimal decoder that dumps the file structure to the console.

There is also a GIMP plugin using libheif here.

HEIF thumbnails for the Gnome desktop

The program heif-thumbnailer can be used as a HEIF thumbnailer for the Gnome desktop. The matching Gnome configuration files are in the gnome directory. Place the file heif.xml into /usr/share/mime/packages and heif.thumbnailer into /usr/share/thumbnailers. You may have to run update-mime-database /usr/share/mime to update the list of known MIME types.


The libheif is distributed under the terms of the GNU Lesser General Public License. The sample applications are distributed under the terms of the MIT License.

See COPYING for more details.

Copyright (c) 2017-2018 Struktur AG Contact: Dirk Farin