AppImage Thumbnailer

An in-process thumbnailer that extracts AppImage icons and writes ready-to-use PNG thumbnails for desktop environments implementing the freedesktop.org spec.

Features

• Supports both SquashFS (traditional) and DwarFS AppImage formats.
• Resolves .DirIcon pointers (with bounded symlink depth).

Prerequisites

• Tooling: meson (>=1.1) and ninja for builds.
• Runtime requirements:
  • unsquashfs from squashfs-tools for SquashFS AppImages (traditional format). Available in all major distro repos. Optionally bundled at build time with -Dbundle_squashfs=true.
  • dwarfsextract from dwarfs for DwarFS AppImages — bundled automatically during build.
• Linked system libraries (usually present on major distros): GLib/GIO (>=2.56), GdkPixbuf (>=2.42), librsvg (>=2.54), Cairo, and libm (optional but detected).
• Platform: a freedesktop.org-compliant thumbnail cache (GNOME, KDE, etc.).

Build & Install

Installing Dependencies (click to open)

Fedora / RHEL / CentOS:

sudo dnf install meson ninja-build squashfs-tools glib2-devel gdk-pixbuf2-devel librsvg2-devel cairo-devel

Additional packages required when bundling unsquashfs (-Dbundle_squashfs=true) or dwarfsextract (-Dbundle_dwarfs=true, enabled by default):

sudo dnf install curl zlib-devel libzstd-devel xz-devel

Ubuntu / Debian:

sudo apt install meson ninja-build squashfs-tools libglib2.0-dev libgdk-pixbuf-2.0-dev librsvg2-dev libcairo2-dev

Additional packages required when bundling unsquashfs or dwarfsextract:

sudo apt install curl zlib1g-dev libzstd-dev liblzma-dev

Arch Linux:

sudo pacman -S meson ninja squashfs-tools glib2 gdk-pixbuf2 librsvg cairo

Additional packages required when bundling unsquashfs or dwarfsextract:

sudo pacman -S curl zlib zstd xz

git clone https://github.com/kem-a/appimage-thumbnailer.git
cd appimage-thumbnailer
meson setup build
ninja -C build
sudo ninja -C build install

Installation drops the appimage-thumbnailer binary and appimage-thumbnailer.thumbnailer descriptor under your Meson prefix (default /usr/local).

Uninstall with sudo ninja -C build uninstall using the same build directory.

(Optional) Remove thumbnail background

Remove checkered alpha channel drawing around thumbnails and icons in Nautilus. Creates more cleaner look.

Edit ~/.config/gtk-4.0/gtk.css file and add CSS code snippet to it:

/*Clear Nautilus thumbnail background*/
.thumbnail,
.icon .thumbnail,
.grid-view .thumbnail {
  background: none;
  box-shadow: none;
}

More help

Type appimage-thumbnailer --help for more info

Troubleshooting

1. If icons do not refresh immediately, clear cached entries and reopen your file manager:

rm -rf ~/.cache/thumbnails/*

2. SELinux blocking unsquashfs and appimage-thumbnailer. This can happen on distros like Fedora that uses selinux.

   • Error: SELinux is preventing unsquashfs from create access on the lnk_file .DirIcon. Allow this access for now by executing:

   sudo su
   ausearch -c 'unsquashfs' --raw | audit2allow -M my-unsquashfs
   semodule -X 300 -i my-unsquashfs.pp

   • Error: SELinux is preventing appimage-thumbn from unlink access on the lnk_file .DirIcon. Allow this access for now by executing:

   sudo su
   ausearch -c 'appimage-thumbn' --raw | audit2allow -M my-appimagethumbn
   semodule -X 300 -i my-appimagethumbn.pp

3. Run thumbnailer manually to test if icon is extracted

appimage-thumbnailer sample.AppImage icon.png 256

License

This project is licensed under the MIT License. See LICENSE for details.