How AppImage Icons Are Stored and Found

Where the icon lives

A typical image, with the icon name myapp. Indented entries are inside the folder above them.

• AppRun
• myapp.desktop: contains Icon=myapp
• myapp.png: the icon named in the desktop file
• .DirIcon: a symbolic link to myapp.png
• usr/share/icons/hicolor/
  • 48x48/apps/myapp.png
  • 256x256/apps/myapp.png
  • scalable/apps/myapp.svg

The rules behind this layout:

• Icon= should name the icon without a file extension; the file itself carries one. appimagetool looks for .png, .svg or .xpm in the root.
• appimagetool refuses to build an AppImage when no root file matches the Icon= name, and creates .DirIcon as a symbolic link to that file when the AppDir has none.
• The specification asks for .DirIcon to be a 256×256 PNG, and for a root PNG icon of 256, 512 or 1024 pixels.
• Icons below usr/share/icons/hicolor follow the Icon Theme Specification, one folder per size (48x48, 256x256, scalable). When they exist, the AppImage specification prefers them as the icon that represents the AppImage; the root icon comes next.

How a reader finds it

On an installed system, the Desktop Entry Specification decides: an Icon= value that is an absolute path is used as it is, and a name is looked up through the icon theme, then its parent themes, then hicolor, and finally unthemed icons such as /usr/share/pixmaps. An AppImage carries the same folders inside its image, so a reader of the file looks in the same places, relative to the image root.

A file reached in several ways, for example the root icon that .DirIcon points to, is listed once and marked with a note (“Also the .DirIcon of the AppImage.”). Files with identical content are merged. The list is sorted by size, so the steps above decide what is found, not which icon comes first.

Links inside the image

.DirIcon is often a symbolic link, and root icon files are often links into usr/share/icons. A reader of the file has to follow them inside the image. UNQIRO follows relative link targets, at most 8 in a row, and .. never leads above the image root.

Absolute targets such as /usr/share/icons/… point into the system the AppImage would run on, not into the AppImage, so they are not followed. The same applies to an Icon= value that is a path instead of a name.

Why an AppImage shows a generic icon

Each step of the chain can fail on its own. The ones to check first:

• No usable Icon= value. Without a name, or with an absolute path, only .DirIcon remains to be found inside the image.
• The name does not match a file. Icon=myapp with a file called my-app.png finds nothing. appimagetool refuses to build such an AppDir, but an AppImage made another way can still contain the mismatch.
• A broken link. .DirIcon points to a file that is not in the image, or to an absolute path outside it.
• A format the program cannot draw. XPM icons and SVG files with scripts or references to other files are not drawn everywhere. UNQIRO lists both, but draws neither.
• Nothing reads the icon. A file manager shows the AppImage’s own icon only if something reads it; the AppDir documentation names thumbnailers as a user of .DirIcon. Menus show the application icon only after the desktop file and icon are integrated into the system.

When UNQIRO finds none of the files, it says so: “No icon was found in this AppImage: it has no .DirIcon and no icon file named in its desktop file.”

PNG, SVG and XPM icons

• PNG icons are shown with their real size from the PNG header and saved unchanged.
• SVG icons are checked first. Safe ones are drawn at 1024 pixels on the longer side; SVG files with scripts or references to other files are listed, not drawn.
• XPM icons are listed with their size but not converted.

How the icon files fit into the whole file is explained in AppImage file structure: ELF runtime and SquashFS.