gnome-software-plugin-appimage

A GNOME Software plugin that adds AppImage support, the way gnome-software-plugin-flatpak adds Flatpak support.

Flatpak already has first-class desktop integration through GNOME Software. AppImage does not: distro-independent, self-contained AppImage bundles are an increasingly common (sometimes only) Linux release format, but nothing system-native turns "double-click an .AppImage file" into "it's an app in my launcher, and I can update or remove it later". Tools like Gear Lever fill that gap today as a separate application; this plugin folds the same basic capability into Software itself.

Installing

Packages are published to this repo's Debian package registry:

sudo curl https://git.batts.cloud/api/packages/vbatts/debian/repository.key -o /etc/apt/keyrings/forgejo-vbatts.asc
echo "deb [signed-by=/etc/apt/keyrings/forgejo-vbatts.asc] https://git.batts.cloud/api/packages/vbatts/debian trixie main" | sudo tee /etc/apt/sources.list.d/forgejo-vbatts.list
sudo apt update
sudo apt install gnome-software-plugin-appimage gnome-appimage-updates

gnome-appimage-updates is optional — see AppImage Updates below. You can also grab the .deb files directly from a release and install with sudo apt install ./package.deb.

Using it

Once installed, a file manager (Nautilus, Files, etc.) will offer "Software Install" as the way to open .AppImage files — either as the default action on double-click, or under "Open With". Picking it:

1. Opens GNOME Software straight to an install page for the app, showing its real name, summary and icon — read straight out of the AppImage's own embedded .desktop file, not a generic "Unknown" placeholder.
2. Clicking Install copies the AppImage into ~/AppImages/, makes it executable, and drops a .desktop launcher (with its icon) into $XDG_DATA_HOME/applications/. The app now shows up in the GNOME Shell app grid and search, and in Software's Installed tab, like any other app — you no longer need to remember where you downloaded it, or that it was even an AppImage.
3. It can be launched from the app grid, from search, or from Software's Installed tab, same as anything else.
4. Uninstalling it from Software (or gnome-software --local-filename) removes the copy under ~/AppImages/, its .desktop file, and its icon — no leftovers.
5. If you quit and restart Software (or reboot), previously-installed AppImages are rediscovered automatically by scanning for the .desktop files this plugin wrote, so they keep showing as installed and removable.

If squashfs-tools isn't installed, or the AppImage doesn't embed a .desktop file the way the spec expects, install/launch/uninstall still work — you just get a generic name (the filename) and a generic icon instead of the app's real branding.

If an already-installed AppImage is opened again under a different filename (e.g. a fresh download replacing an old one), the plugin notices another installed app has the same name and asks whether to replace it in place, rather than silently installing a second copy.

For apps with an update source configured in gnome-appimage-updates (see below), GNOME Software's normal "check for updates" also checks each one and offers a regular update when a newer release is found.

AppImage Updates

gnome-appimage-updates is a small separate GTK4/libadwaita app for telling AppImages in ~/AppImages/ where to look for a newer release, when they don't embed that information themselves (most don't). For each file it lets you set either:

• a static URL pattern (with * where the version number goes), plus an optional "version check page" — a page (e.g. a "latest release" page) whose text names the current version, which gets substituted into the pattern's * to build the real download URL. Without a check page, the plugin falls back to comparing the URL's Content-Length to the installed file's size (the same thing GearLever does), which can only notice that something changed, not what.
• a GitHub repo + release-asset filename pattern, checked against the GitHub Releases API directly.

It's deliberately narrow: it only ever writes that update-source config — it never touches .desktop files, so it doesn't install/uninstall apps or add/remove them from the app grid (that's this plugin's job, via GNOME Software). Each row does show whether a .desktop file already exists for that AppImage, so you can tell at a glance.

It reads and writes $XDG_CONFIG_HOME/gnome-software-plugin-appimage/updates.conf, using the same GKeyFile schema and md5(file_path)-based app IDs as Gear Lever's own gearlever.conf — so the "Reconcile from GearLever" button can one-way import update sources you've already configured there, without ever writing back to GearLever's own config.

GNOME Software's own periodic/manual "check for updates" is what actually checks these sources (via the plugin's refresh_metadata) — this app only ever edits where to look, never triggers a check itself.

How it works

AppImage files embed a filesystem (almost always squashfs, "type 2" in the AppImage spec) containing an AppDir with a .desktop file and an icon. This plugin never executes the untrusted AppImage to get at that data: it parses the ELF header itself to work out where the squashfs payload starts, then shells out to unsquashfs -o <offset> (from squashfs-tools) to extract just the .desktop file and icon.

Legacy "type 1" (ISO9660) AppImages are recognized and can still be installed and launched, just without the rich metadata/icon extraction step above.

Building

meson setup build
ninja -C build
sudo ninja -C build install

Requires gnome-software-dev, libappstream-dev, libxmlb-dev, libglib2.0-dev, libsoup-3.0-dev and libjson-glib-dev to build the plugin, and squashfs-tools at runtime. Building gnome-appimage-updates additionally needs libgtk-4-dev and libadwaita-1-dev (pass -Dupdates_tool=false to skip it).

Packaging

A Debian source package is included:

dpkg-buildpackage -us -uc

Roadmap

• Parse embedded AppStream usr/share/metainfo/*.xml (many AppImages ship one) for richer name/description/screenshots instead of just the .desktop file.
• Check for updates against the AppImage's own embedded .upd_info (zsync / GitHub Releases / Pling) when present, not just what's configured in gnome-appimage-updates.
• Version comparison for update checking is a simple dotted-numeric compare, not full semver — good enough for typical X.Y.Z-style releases, but not for every versioning scheme in the wild.