HEIC on Linux: open, convert and fix codec errors

How does Linux open a HEIC file?

Through libheif, an ISO/IEC 23008-12 HEIF and AVIF decoder and encoder. Almost every Linux program that reads HEIC calls it: libheif's own README lists GIMP, Krita, ImageMagick, GraphicsMagick, darktable, digiKam, libvips, pillow-heif, KDE's KImageFormats, XnView and the GNOME desktop through a gdk-pixbuf loader. libheif does not decompress the photo itself. It hands the image to a codec library.

The README's codec table says HEIC is decoded by libde265 or FFmpeg and encoded by x265 or kvazaar; AVIF uses libaom, dav1d, svt-av1 or rav1e. Since libheif 1.14.0 each codec can be a separate plugin loaded from the directories in the LIBHEIF_PLUGIN_PATH environment variable, which is how distributions split them into packages, and the README says the FFmpeg decoder plugin still prefers libde265 when both are present. The README also notes that x265 is GPL and that kvazaar (BSD) is an alternative encoder. Its October 2026 status note says libheif and libde265 are maintained by one independent developer who handled 73 security advisories in 2026, so keep both up to date.

Why does Linux say 'unsupported codec' for my HEIC?

Because libheif found no HEVC decoder. We reproduced it. This machine runs Ubuntu 24.04.5 with libheif 1.17.6 and only the AV1 decoder plugin in its plugin directory, which is what the libheif1 package depends on. The same file opens fine in pillow-heif on the same machine, so the photo is not damaged.

How do I open HEIC on Ubuntu, Linux Mint, Fedora or Arch?

Is there a 'HEIC extension' for Ubuntu? No. There is no Store-style add-on; the pieces are the packages above. In the GNOME desktop, heif-gdk-pixbuf adds the loader that gdk-pixbuf programs use and heif-thumbnailer registers a thumbnailer for image/heif and image/avif. The Ubuntu 24.04 index shows gnome-control-center and Shotwell depending on both, and ubuntu-desktop depending on Eye of GNOME (eog). Those still need an HEVC decoder underneath to show an iPhone photo.

Fedora and the Fedora forum describe the same split from the other side. A forum reply from March 2025 (a user's reading, not a Fedora statement) says libheif-freeworld supplements libheif with components Fedora cannot ship. The RPM Fusion configuration page says its free repository holds open-source software Fedora cannot ship 'for other reasons'.

Which Linux viewers and file managers open HEIC?

• GNOME Loupe and Nautilus: Loupe is GNOME's default Image Viewer and loads images through glycin, whose HEIF loader uses libheif. The glycin README lists Nautilus among its users and ships a thumbnailer. Loupe's own README says which formats work depends on the glycin loaders installed. Ubuntu 24.04 has Loupe 46.2 in universe; its default desktop depends on Eye of GNOME instead.
• Eye of GNOME and gdk-pixbuf programs: the libheif README says the GNOME desktop reads HEIC through the gdk-pixbuf loader that libheif includes. We did not test Eye of GNOME itself.
• KDE: KImageFormats lists HEIC, HEIF and HIF as read and write 'dependent on the HEIF plugins installed'. Upstream, its HEIF plugin is off unless built with KIMAGEFORMATS_HEIF, because it needs a libheif with HEVC. Ubuntu 24.04's kimageformat-plugins depends on the libde265 and x265 plugins. We did not verify Gwenview or Dolphin specifically.
• Shotwell: its NEWS file says 'Support HEIF/HEVC files' arrived in 0.31.90 (April 2023) and 'Support more variants of HEIF' in 0.32.0.
• digiKam: the libheif README lists it as a libheif user. digiKam's manual lists HEIF but says no definitive format list is possible, because availability depends on the libraries on your system and how they were compiled.
• GIMP: only if its libheif has an HEVC decoder; see HEIC in Photoshop, Lightroom and GIMP.

How do I convert HEIC on the Linux command line?

Each line below is marked. 'Ran' means we executed it here on 12 October 2026 and report what happened; 'Not run' means it comes from documentation or is a standard shell pattern.

Does ImageMagick support HEIC?

Yes, with a libheif delegate. The ImageMagick format list says HEIC is read and write and 'requires the libheif delegate library', with defines such as heic:speed, heic:chroma and heic:preserve-orientation. Two things in our run are worth knowing.

• Version 6 in Ubuntu 24.04 reads, but does not write: convert -list format showed HEIC r-- Apple High efficiency Image Format (1.17.6). Writing gave no encode delegate for this image format 'HEIC' as a warning with exit code 0, and the file it left behind named photo.heic was a JPEG (file reported JPEG image data). Check the file type if you rely on the exit code.
• The security policy can block it: ImageMagick's recommended strict policy denies all image modules and permits only GIF, JPEG, PNG and WEBP. We copied the policy-websafe.xml shipped with Ubuntu's ImageMagick 6 into a scratch folder and, with a working libde265 plugin, got attempt to perform an operation not allowed by the security policy 'HEIC' and no decode delegate for this image format 'HEIC'. If HEIC works on the command line but not on a web server, look at policy.xml. ImageMagick's page adds that before 7.1.1-16 policy patterns are case-sensitive, so coder names must be upper case.

Does FFmpeg support HEIC?

Only since version 7.0, and fully only in newer builds. FFmpeg's changelog lists 'Support for HEIF/AVIF still images and tiled still images' under 7.0 and 'ffmpeg CLI tiled HEIF support' under 8.1. FFmpeg decodes HEVC with its own decoder (our 7.0.2 run mapped 'hevc (native)'), so it needs no libde265. The newest stable release on ffmpeg.org is 9.0.2 (18 September 2026), but Ubuntu 24.04 ships 6.1.1.

• FFmpeg 6.1.1 (Ubuntu package): moov atom not found then Error opening input: Invalid data found when processing input, exit code 183, on both files.
• FFmpeg 7.0.2 (static build): the single image decoded as a 640 x 480 HEVC (Main Still Picture) stream. For the tiled file it listed a 'Tile Grid' stream group of 4032 x 3024 but wrote a 1024 x 1024 PNG, one tile.
• FFmpeg built from master on 11 October 2026: wrote the full 4032 x 3024 PNG.
• Writing HEIC: the master build's muxer list had avif but no HEIC or HEIF, and ffmpeg -i test.heic out.heic stopped with Unable to choose an output format for 'out.heic'. We found no HEIC muxer in the documentation we read, so use pillow-heif or heif-enc to make HEIC.

So on a stock Ubuntu 24.04 an FFmpeg pipeline cannot read HEIC at all, and with 7.0 it can read most files but may silently return one tile of an iPhone photo. Check the output size against the input.

How do I use HEIC in Python (pillow-heif)?

Install it with pip. pillow-heif's documentation says wheels exist for most popular systems and are built with libheif and its encoders and decoders. We confirmed that on this machine: the wheel's pillow_heif.libs folder holds libheif 1.23.4, libde265 and x265, and pillow_heif.libheif_info() reports the libde265 decoder and the x265 encoder. That is why it opened both test files while ImageMagick, using the system libheif 1.17.6, could not. For Node, Go, Rust, Java and .NET, and for batch recipes, see HEIC for developers.

• Plain Pillow does not read HEIC: Image.open('test.heic') raised UnidentifiedImageError: cannot identify image file 'test.heic' until pillow_heif.register_heif_opener() was called.
• Reading and saving: after registering, Image.open returned a 640 x 480 RGB image and save('photo.jpg') worked. im.save('x.heic', quality=70) wrote a HEIC, and tile_size=1024 produced the tiled file we used above.
• Building from source needs libheif 1.23.4 or newer, libde265 1.0.8 or newer and aom 3.3.0 or newer, according to its documentation, which also says distribution packages are too old for that.

Does exiftool read HEIC metadata?

Yes. ExifTool's supported-types table lists HEIC, HEIF and HIF as read and write. We ran version 13.59 on a sample HEIC with EXIF and GPS and it printed the capture date, make, model and GPS position, then wrote an Artist tag to a copy and read it back. Keep it current: its known-problems list records fixes in 13.09 (an HDR gain-map HEIC could lose its gain map in Apple Preview after XMP was added) and 13.49 (motion-photo HEIC after editing). Our metadata viewer shows the same tags in your browser, and Remove HEIC GPS strips location without any install.

Why do Fedora and Ubuntu handle HEIC differently?

Patents. GIMP's developer documentation puts it bluntly: 'HEVC has patent issues, unlike its AVIF counterpart', which is 'why many Free Software distributors do not wish to package HEIC support'. Fedora's documentation says its repositories leave out some codecs for patent or licensing reasons and sends users who want HEVC to RPM Fusion. Ubuntu ships the libde265 plugin in its main archive component in 24.04. We are not lawyers and this page does not say what is legal where you are; it says what each distribution packages.

When should I just use a browser tool instead?

When you lack root, when the machine is a work laptop, when you have a handful of photos, or when your distribution's libheif is the problem. Our converter decodes HEIC in your browser with WebAssembly, so it behaves the same on every distribution. Limits: 100 MB per file, 100 megapixels per image, and 50 files or 500 MB per batch. Nothing is uploaded. The JPG keeps the capture date and camera details by default, while GPS is left out unless you switch on Include location (GPS).

To see why one file opens and another does not, run it through the HEIC file checker and read HEIC vs HEIF for the container-versus-codec split. Windows and Mac readers have their own guides: Open HEIC on Windows and HEIC to JPG on Mac.