.APPIMAGE File Format – AppDir contents

AppImage application

The filesystem image inside an AppImage is an AppDir, an application folder in the style of the ROX desktop. appimagetool turns such a folder into an AppImage, and --appimage-extract turns an AppImage back into one (squashfs-root/). This page follows the AppImage Specification draft; the words “must”, “should” and “may” have their RFC 2119 meanings.

Files at the root

PathRuleContents
AppRunMustThe entry point the runtime executes; see AppRun.
appname.desktopShould, exactly oneA Desktop Entry file for the payload application (name, Exec, Icon, categories).
.DirIconMustThe folder’s icon, as the AppDir specification describes; should be a 256×256 PNG.
icon.svg, .svgz or .pngMayThe icon named by the desktop file’s Icon= key. Preferred when there is no matching icon under usr/share/icons/hicolor. A PNG should be 256×256, 512×512 or 1024×1024 pixels.
usr/RecommendedThe payload and its libraries, laid out like the Filesystem Hierarchy Standard’s /usr (usr/bin, usr/lib, usr/share).
usr/share/icons/hicolor/…ShouldIcons following the freedesktop Icon Theme Specification, matching Icon=; preferred over the root icon.
usr/share/metainfo/id.appdata.xmlShouldAppStream metadata (description, screenshots, releases), following the AppStream guidelines, named by the AppStream ID.
 
MyApp.AppDir/
  AppRun
  myapp.desktop
  myapp.png
  .DirIcon -> myapp.png
  usr/
    bin/myapp
    lib/libfoo.so.1
    share/
      icons/hicolor/256x256/apps/myapp.png
      metainfo/org.example.myapp.appdata.xml
A typical AppDir.

AppRun

  • Must be executable and must start the payload application, directly or indirectly.
  • May be an ELF program (with as few dependencies as possible) or a script in a language whose interpreter every target system can be assumed to have.
  • Must work from a path that contains spaces.
  • Should pass on its arguments and environment variables to the payload.
  • May change into a folder inside the image first, usually ./usr/.

A custom AppRun can read $ARGV0 (the name the AppImage was started by) to choose which of several programs to run, BusyBox-style.

Payload application

The payload may be an ELF program or a script. Any library or interpreter that cannot be assumed to be present, in a recent enough version, on every target system must be included in the image. The AppImage’s author should state which systems it targets.

Desktop integration

Software may add an AppImage to the desktop’s menus (by installing its desktop file and icon on the host) and should ask the user first. It should not do so when any of these holds:

  • $XDG_DATA_HOME/appimagekit/no_desktopintegration exists;
  • /usr/share/appimagekit/no_desktopintegration exists;
  • /etc/appimagekit/no_desktopintegration exists;
  • a process called appimaged is running;
  • the variable $DESKTOPINTEGRATION is not empty.

Sources

AppImage Specification, working draft (draft.md in the AppImageSpec repository): “Image contents”, “Metadata” and “Desktop integration”; AppImage documentation, “Environment variables” (ARGV0) and “Running AppImages” (squashfs-root). The AppDir drawing is an illustration, not taken from a specification.