libheif 是一个 HEIF 和 AVIF 文件格式解码器和编码器。
libheif is an ISO/IEC 23008-12 HEIF and AVIF (AV1 Image File Format) file format decoder and encoder. HEIC and AVIF are new image file formats employing HEVC (H.265) or AV1 image coding, respectively, for the best compression ratios currently possible.
On top of HEIC and AVIF, libheif also supports HEIF images coded with VVC, AVC, JPEG, JPEG-2000, and ISO/IEC 23001-17. The ISO/IEC 23001-17 codec is built-in to libheif and allows to store lossless images and video in many different formats.
libheif makes use of various codec libraries for implementing each compression format. For HEIC, libde265 is used by default for decoding and x265 for encoding. For AVIF, libaom, dav1d, svt-av1, or rav1e are used as codecs. libheif can be built with a subset of the supported codecs to keep the size and the number of dependencies low. Alternatively, the libheif codecs can also be built as separate plugins that can be installed and loaded dynamically when used.
Project status (August 2026). libheif and libde265 are maintained by a single independent developer with almost no recurring funding, while 37 security advisories had to be investigated, fixed and released in 2026 alone. If libheif is part of your product or service, please read Funding and Commercial support. Security issues are reported as described in SECURITY.md.
libheif has support for:
Supported codecs:
Format Decoders Encoders HEIC libde265, ffmpeg x265, kvazaar AVIF libaom, dav1d, ffmpeg libaom, rav1e, svt-av1 VVC vvdec, ffmpeg vvenc, uvg266 AVC openh264, ffmpeg x264 JPEG libjpeg(-turbo), ffmpeg libjpeg(-turbo) JPEG2000 OpenJPEG, ffmpeg OpenJPEG HTJ2K OpenJPEG, ffmpeg OpenJPH uncompressed built-in built-inThe library has a C API for easy integration and wide language support.
The decoder automatically supports both HEIF and AVIF (and the other compression formats) through the same API. The same decoding code can be used to decode any of them.
The encoder can be switched between HEIF and AVIF simply by setting heif_compression_HEVC or heif_compression_AV1
to heif_context_get_encoder_for_format(), or using any of the other compression formats.
…
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, image, encoder, nullptr, nullptr);
heif_encoder_release(encoder);
heif_context_write_to_file(ctx, "output.heic");
heif_context_free(ctx);
heif_item_id exif_id;
int n = heif_image_handle_get_list_of_metadata_block_IDs(image_handle, "Exif", &exif_id, 1);
if (n==1) {
size_t exifSize = heif_image_handle_get_metadata_size(image_handle, exif_id);
uint8_t* exifData = malloc(exifSize);
struct heif_error error = heif_image_handle_get_metadata(image_handle, exif_id, exifData);
}
See the image sequences API documentation.
Since HEIF image sequences are very similar to MP4 video, libheif can also read and write MP4 video (without audio) with all supported codecs.
For very large resolution images, it is not always feasible to process the whole image.
In this case, libheif can process the image tile by tile.
See the image tiling API documentation.
See the header files 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.
This library uses the CMake build system (the earlier autotools build files have been removed in v1.16.0).
For a minimal configuration, we recommend to use the codecs libde265 and x265 for HEIC and AOM for AVIF. Make sure that you compile and install libde265 first, so that the configuration script will find this. Also install x265 and its development files if you want to use HEIF encoding, but note that x265 is GPL. An alternative to x265 is kvazaar (BSD).
The basic build steps are as follows (--preset argument needs CMake >= 3.21):
mkdir build
cd build
cmake --preset=release ..
make
There are CMake presets to cover the most frequent use cases.
release: the preferred preset which compiles all codecs as separate plugins.
If you do not want to distribute some of these plugins (e.g. HEIC), you can omit packaging these.release-noplugins: this is a smaller, self-contained build of libheif without using the plugin system.
A single library is built with support for HEIC and AVIF.testing: for building and executing the unit tests. Also the internal library symbols are exposed. Do not use for distribution.fuzzing: all codecs like in release build, but configured into a self-contained library with enabled fuzzers. The library should not distributed.You can optionally adapt these standard configurations to your needs.
This can be done, for example, by calling ccmake . from within the build directory.
Libheif supports many different codecs. In order to reduce the number of dependencies and the library size, you can choose which of these codecs to include. Each codec can be compiled either as built-in to the library with a hard dependency, or as a separate plugin file that is loaded dynamically.
For each codec, there are two configuration variables:
WITH_{codec}: enables the codecWITH_{codec}_PLUGIN: when enabled, the codec is compiled as a separate plugin.In order to use dynamic plugins, also make sure that ENABLE_PLUGIN_LOADING is enabled.
The placeholder {codec} can have these values: LIBDE265, X265, AOM_DECODER, AOM_ENCODER, SvtEnc, DAV1D, OpenH264, X264, FFMPEG_DECODER, JPEG_DECODER, JPEG_ENCODER, KVAZAAR, OpenJPEG_DECODER, OpenJPEG_ENCODER, OPENJPH_ENCODER, VVDEC, VVENC, UVG266, WEBCODECS.
Further options are:
WITH_UNCOMPRESSED_CODEC: enable support for uncompressed images according to ISO/IEC 23001-17:2024. This is experimental
and not available as a dynamic plugin. When enabled, it adds a dependency to zlib, and optionally will use brotli.WITH_HEADER_COMPRESSION: enables support for compressed metadata. When enabled, it adds a dependency to zlib.
Note that header compression is not widely supported yet.WITH_LIBSHARPYUV: enables high-quality YCbCr/RGB color space conversion algorithms (requires libsharpyuv,
e.g. from the third-party directory).ENABLE_EXPERIMENTAL_FEATURES: enables functions that are currently in development and for which the API is not stable yet
and may contain security risks. When this is enabled, a header heif_experimental.h will be installed that contains this
unstable API. Distributions should not enable this in release or production builds.ENABLE_MULTITHREADING_SUPPORT: can be used to disable any multithreading support, e.g. for embedded platforms.ENABLE_PARALLEL_TILE_DECODING: when enabled, libheif will decode tiled images in parallel to speed up compilation.PLUGIN_DIRECTORY: the directory where libheif will search for dynamic plugins when the environment
variable LIBHEIF_PLUGIN_PATH is not set.WITH_REDUCED_VISIBILITY: only export those symbols into the library that are public API.
Has to be turned off for running some tests.Install dependencies with Homebrew
brew install cmake make pkg-config x265 libde265 libjpeg libtool
Configure and build project (--preset argument needs CMake >= 3.21):
mkdir build
cd build
cmake --preset=release ..
./configure
make
You can build and install libheif using the vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat
./vcpkg integrate install
./vcpkg install libheif
The libheif port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.
aom.cmd script in the third-party directory to download libaom and
compile it.When running cmake or configure, make sure that the environment variable
PKG_CONFIG_PATH includes the absolute path to third-party/aom/dist/lib/pkgconfig.
cargo.cargo-c by executingcargo install --force cargo-c
rav1e.cmd script in the third-party directory to download rav1e
and compile it.When running cmake, make sure that the environment variable
PKG_CONFIG_PATH includes the absolute path to third-party/rav1e/dist/lib/pkgconfig.
meson.dav1d.cmd script in the third-party directory to download dav1d
and compile it.When running cmake, make sure that the environment variable
PKG_CONFIG_PATH includes the absolute path to third-party/dav1d/dist/lib/x86_64-linux-gnu/pkgconfig.
You can either use the SVT-AV1 encoder libraries installed in the system or use a self-compiled current version. If you want to compile SVT-AV1 yourself,
svt.cmd script in the third-party directory to download SVT-AV1
and compile it.You have to enable SVT-AV1 with CMake.
When running cmake, make sure that the environment variable
PKG_CONFIG_PATH includes the absolute path to third-party/SVT-AV1/Build/linux/install/lib/pkgconfig.
You may have to replace linux in this path with your system's identifier.
Starting with v1.14.0, each codec backend can be compiled statically into libheif or as a dynamically loaded plugin.
You can choose this individually for each codec backend in the CMake settings using WITH_{codec}_PLUGIN options.
Compiling a codec backend as dynamic plugin
暂无开放 Issues，或尚未同步最近议题。