AppImage file format: image types and runtime

This page follows the AppImage Specification (a working draft kept by the AppImage project on GitHub) and, where the specification is silent, the project’s reference type 2 runtime and its documentation; those parts are marked. An AppImage must not depend on its file name; .AppImage is recommended, named ApplicationName-version-arch.AppImage when the name carries that information. It must work when its path or the paths inside it contain spaces, and should not be wrapped in another archive for download.

Image types

Type	Layout	Magic at offset 8	Update information
0	Reserved for portable programs that behave like AppImages for the user but do not follow the specification.	—	—
1	A file that is both a valid ELF executable and an ISO 9660 image, with Rock Ridge extensions (required), Joliet (optional) and zisofs compression (recommended). Deprecated.	`41 49 01`, should be present	In the ISO 9660 volume descriptor at offset 33651 (the 512-byte application-use field of the primary volume descriptor, which starts at 32768)
2	A valid ELF executable (the runtime) with a filesystem image appended, which the runtime can mount. The reference runtime uses SquashFS.	`41 49 02`, required	In the ELF section `.upd_info`

Offset 8 lies inside the 16 identification bytes at the start of every ELF header, so the file is still a valid ELF program: 41 49 is ASCII AI, and the third byte is the type.

When run, either type must mount its image and execute the file AppRun at the image’s root (see AppDir contents).

Type 2 layout

0ELF header, with AI 02 at offset 8varies
…runtime: code, data and the AppImage sections belowvaries
…section header tablevaries
offsetSquashFS image, the AppDirto the end

A type 2 AppImage.

The filesystem starts where the ELF file ends. The reference runtime computes that offset as the larger of the end of the section header table (e_shoff + e_shentsize × e_shnum) and the end of the last section, and prints it with --appimage-offset. The image can then be mounted by hand with mount -o offset=….

ELF sections

Section	Size in the reference runtime	Contents
`.upd_info`	1024 bytes	Update information, a NUL-padded ASCII string; empty or ignored if not in a known format.
`.sha256_sig`	1024 bytes	Optional digital signature. Either all `00`, or a valid signature of the SHA-256 digest of the whole AppImage, computed with this section filled with `00`. The signature format is not fixed by the specification.
`.sig_key`	8192 bytes	Reserved by the reference runtime; not in the specification, and its contents are not confirmed here.
`.digest_md5`	16 bytes	Reserved placeholder in the reference runtime (not in the specification).

The sizes come from the reference runtime’s linker script, which reserves the sections filled with zeros so that tools can write into them after building. Readers should take each section’s offset and length from the ELF section headers.

Update information

A single line of fields separated by |, the first naming the transport. An AppImage carries update information for at most one transport. Updaters download only the changed blocks, using a .zsync file published beside the new version.

Transport	Form	Fields
`zsync`	`zsync\|url`	URL of the `.zsync` file, which must not change between versions; the server must support HTTP range requests.
`gh-releases-zsync`	`gh-releases-zsync\|user\|repo\|tag\|file`	GitHub user or organisation, repository, release tag, and the `.zsync` file name with `*` as a wildcard. The tag may be a fixed tag (such as `continuous`) or `latest` (latest release, not prereleases), `latest-pre` (latest prerelease) or `latest-all` (latest of either).
`pling-v1-zsync`	`pling-v1-zsync\|product-id\|pattern`	pling.com product ID and a wildcard pattern for the file names, which must include the architecture and may include a release channel; sorted by name, files must be in release order. Recommended names: `app-version-channel-arch.AppImage`. The `.zsync` file is not uploaded to the store.
`bintray-zsync`	—	Deprecated (it served Bintray); no form is given.

Example: gh-releases-zsync|probono|AppImages|latest|Subsurface-*x86_64.AppImage.zsync.

Runtime

The runtime mounts the image (with FUSE, in a temporary folder /tmp/.mount_nameXXXXXX in the reference runtime) and runs AppRun. The specification requires only TARGET_APPIMAGE (for static runtimes; recommended for all): when it names an existing file, that file’s image is used instead of the one appended to the runtime. The rest of this section describes the reference type 2 runtime.

Options

Arguments starting --appimage- are taken by the runtime; all others are passed to the application.

Option	Action
`--appimage-extract [pattern]`	Extract the image (or the files matching the pattern) into `squashfs-root/` in the current folder.
`--appimage-extract-and-run`	Extract into a temporary folder `appimage_extracted_md5` (named by the file’s MD5), run the application, then delete it unless `NO_CLEANUP` is set. For systems without FUSE.
`--appimage-help`	Print the options.
`--appimage-mount`	Mount the image, print the mount point and wait until interrupted.
`--appimage-offset`	Print the byte offset of the image.
`--appimage-portable-home`	Create `file.home` beside the AppImage and use it as `$HOME`.
`--appimage-portable-config`	Create `file.config` and use it as `$XDG_CONFIG_HOME`.
`--appimage-signature`	Print the signature from `.sha256_sig`.
`--appimage-updateinfo`, `--appimage-updateinformation`	Print the update information from `.upd_info`.
`--appimage-version`	Print the runtime’s version.

Environment variables

Variable	Direction	Meaning
`APPIMAGE`	Set	Absolute path of the AppImage, with symbolic links resolved.
`APPDIR`	Set	Where the image is mounted (or extracted).
`OWD`	Set	The working directory when the AppImage was started.
`ARGV0`	Set	The name or path used to start it (`argv[0]`), such as a symbolic link’s name; type 2 only.
`TARGET_APPIMAGE`	Read	Use this AppImage’s image instead of the appended one.
`APPIMAGE_EXTRACT_AND_RUN`	Read	Behave as if `--appimage-extract-and-run` were given.
`NO_CLEANUP`	Read	Keep the folder that extract-and-run made.
`TMPDIR`	Read	Where extract-and-run makes its folder.
`FUSERMOUNT_PROG`	Read and set	The `fusermount` program to use.
`VERBOSE`	Read	Print diagnostic messages.

Type 1 runtimes set APPIMAGE, APPDIR and OWD only.

Sources

AppImage Specification, working draft (draft.md in the AppImageSpec repository): image types, update information, runtime. AppImage documentation: “Environment variables” and “Running AppImages”. The reference runtime (type2-runtime): runtime.c (options, environment variables, filesystem offset, mount and extract folders) and data_sections.ld (section sizes).

.APPIMAGE File Format – Image types and runtime