iPhone HEIC Photos on Linux: Crashes, Blank Thumbnails, and Finding the One Bad File

You copy a folder of photos off an iPhone onto a Linux machine. Most of them open. Then one of them takes Gwenview down with it, or Dolphin throws thumbnailer crash notifications every time you scroll through the folder, or the thumbnails simply never appear. Reinstalling things doesn’t help, and there’s no obvious difference between the file that crashed and the fifty that didn’t.

What makes iPhone HEIC different from other HEIC

HEIC is a container, and two files with the same extension can be structured very differently inside. Recent iPhone photos use features that a lot of software never encounters anywhere else:

• Tiled images. The primary image is stored as a grid of tiles (a heif-info dump will show something like a 9 x 5 grid) that the decoder has to assemble. A single-image HEIC from a different source never exercises that path.
• Tone-mapped HDR. Since iOS 18, HDR photos carry a tone-mapping item, visible as a tmap entry in the file’s compatible brands, alongside an auxiliary gain map. Decoders that don’t know the brand can pick the wrong item to display, or fall over.
• Auxiliary images generally. Depth maps from Portrait mode and gain maps are extra items in the same file, not separate files.

None of this makes the photo corrupt. It means the file exercises corners of libheif that older versions handled badly, which is why one photo out of fifty is the one that crashes.

Cause one: two Qt plugins fighting over image/heic

This is the KDE-specific failure, and it’s the one that produces a hard crash rather than a blank image. Two different Qt image format plugins can end up installed at once:

• kimg_heif.so, shipped by kimageformats
• libheif’s own Qt plugin, shipped by some distributions separately

Both register themselves for image/heic. Qt loads one, and the mix behaves badly. Check which plugins are in play:

QT_DEBUG_PLUGINS=1 gwenview 2>&1 | grep -i heif

If more than one plugin claims the MIME type, that’s your problem.

Fix it by moving one plugin aside, not by uninstalling a package. Find the file first:

find /usr/lib /usr/lib64 -name 'kimg_heif*' 2>/dev/null

then rename it with a .bak suffix (as root) and restart the application.

The reason to move rather than uninstall: kimageformats is also what decodes AVIF, JPEG XL, PSD, TGA and EXR on your system. Removing the package to fix HEIC quietly costs you every other format it handles. Do also note that a package update can reinstall the plugin and bring the crash back, at which point you move it aside again.

Cause two: libheif is too old for the file

If there’s only one plugin and things still break, the decoder itself is behind. Check what you have:

heif-info --version 2>/dev/null || heif-convert --version

Tiled images and tmap HDR support both improved substantially in recent libheif releases, so a distro shipping an older version will struggle with photos from a current iPhone while handling older ones fine.

On distributions that split libheif into a base package and a separate one carrying the patent-encumbered decoders (Fedora’s libheif plus RPM Fusion’s libheif-freeworld, for example), upgrade both together and keep them at the same version. Upgrading one and leaving the other behind is its own class of breakage.

The Flatpak trap: if the failing application is a Flatpak, upgrading libheif on the host changes nothing. Flatpaks bundle their runtime, so the app keeps using the libheif inside it. This catches people who have already upgraded the system library and concluded the version wasn’t the issue. Test with the distro-packaged build of the same app to tell the two apart.

And the trap runs in the other direction, which is the more confusing half. Installing the Flatpak build of a viewer, watching it open the photos that used to crash, and concluding the problem is solved does not hold up: it fixed that one application and nothing else on the system. Everything outside the sandbox, the file manager’s thumbnails above all, is still going through the host libheif. There are two copies of the library on the machine at that point, and only one of them has been dealt with.

See your photos right now

Independent of the fix, you can stop being blocked in about ten seconds by pointing HEIC at a viewer built on a different stack:

xdg-mime default org.gnome.Loupe.desktop image/heic

(or org.gnome.eog.desktop on systems still shipping Eye of GNOME). If those open the same file that crashed Gwenview, you’ve also proved the photo is fine and the problem is on the KDE decoding path.

Thumbnails are a separate problem from viewing

Missing HEIC thumbnails and crash notifications while scrolling a folder both come from the file manager generating previews, not from you opening anything. This matters more than it sounds, because the thumbnailer takes a different route to the same photo than your image viewer does.

Dolphin generates previews itself, on the host, loading HEIC through kimageformats and the host copy of libheif. No viewer is involved. So the usual moves have no effect here:

• Installing a Flatpak viewer that opens the photos fine changes nothing about thumbnails, because the sandbox is not where thumbnails are made.
• Setting a different application as the default for image/heic changes nothing either, for the same reason.

Thumbnails follow the host decoding stack and only the host decoding stack. Fix that (the plugin conflict, or the host libheif version) and they come back.

Then clear the thumbnail cache, or you won’t believe the fix worked. A thumbnail that failed to generate is cached as a failure, and the file manager does not retry it the next time you open the folder. After any fix:

rm -rf ~/.cache/thumbnails/*

Reopen the folder afterwards. Skipping this step is the most common reason people conclude a working fix did nothing.

If you would rather stop the notifications immediately and deal with the decoder later, turn that one preview type off: Dolphin > Settings > Configure Dolphin > General > Previews, and untick the HEIF/HEIC entry. Browsing works normally again, and you keep thumbnails for every other format.

Find the exact file that causes it

Guessing which photo is the trigger is miserable. Ask libheif instead:

find . -iname '*.heic' -print0 | while IFS= read -r -d '' f; do
  printf '%s: ' "$f"
  if heif-info "$f" >/dev/null 2>&1; then echo ok; else echo FAIL; fi
done

Every file is named as it’s tested, so a file that hangs or kills the loop is identified by the last line printed even when it doesn’t fail cleanly.

Then look at the one that failed:

heif-info bad.HEIC

The output tells you whether the primary image is tiled, which brands the file declares, and what auxiliary images are attached. That’s usually enough to know whether you’re looking at the tiled-image path, the HDR path, or a genuinely truncated file from an interrupted transfer.

Converting in bulk, if you’d rather not fight the viewer

For a photo library that keeps causing trouble, or one headed for other machines, converting once is less work than keeping every viewer on every device happy:

for f in *.HEIC; do heif-convert "$f" "${f%.HEIC}.jpg"; done

If ImageMagick on your system was built with a HEIC delegate, magick mogrify -format jpg *.HEIC does the same thing.

Worth knowing if these photos are also going to a Windows machine: Windows has its own version of this problem, because it ships no HEVC decoder by default. Converting once on Linux solves both. For the Windows side of it, this site’s app, HEIC Batch Converter (disclosure: made by the author of this site), does folder-level conversion there. It’s Windows only, so on Linux the heif-convert loop above is the equivalent.

Bottom line

Symptom	Cause	Fix
Viewer crashes on one photo	Two Qt plugins claiming image/heic	Move kimg_heif.so aside
Crashes on all recent iPhone photos	libheif too old for tiles / tmap	Update libheif, or the Flatpak runtime
Crash notifications while browsing	File manager thumbnailer	Disable HEIF previews in Dolphin
No thumbnails, but a Flatpak viewer opens the photos	Thumbnails use the host libheif, not the sandbox	Fix the host stack; the Flatpak can’t help here
Thumbnails still blank after fixing libheif	Failed thumbnails are cached and never retried	rm -rf ~/.cache/thumbnails/*
Need the photos visible now	Any of the above	xdg-mime default to another viewer
Which file is it?	Unknown	find loop with heif-info