How to create a launchable AppImage for elementary OS

An AppImage packages a Linux application and many of its dependencies into a single executable file. Users can download it, make it executable, and run it without a traditional installation process or administrator password. For elementary OS users, this can be a convenient way to distribute software that is not available in AppCenter or in the standard repositories.

The format is especially useful for independent developers, small teams, and utilities that need to reach several Linux distributions. A well-built AppImage can work across compatible releases while keeping the host system clean. It can also be added to the applications menu, assigned an icon, and launched like a native elementary OS program.

There are a few details that determine whether the result feels polished. The bundle needs a valid directory layout, a desktop entry, an icon, executable permissions, and libraries built for an appropriate Linux baseline. Testing on a clean system is just as important as producing the file itself.

Prepare the application and build environment

An AppImage is built from an AppDir directory. This directory mirrors the structure of a Linux filesystem, with the main executable under usr/bin, shared resources under usr/share, and a desktop entry under usr/share/applications. The top level also contains an AppRun launcher and at least one application icon.

A simple layout might look like this:

MyEditor.AppDir/
├── AppRun
├── usr/
│   ├── bin/
│   │   └── myeditor
│   └── share/
│       ├── applications/
│       │   └── myeditor.desktop
│       └── icons/
│           └── hicolor/
│               └── 256x256/
│                   └── apps/
│                       └── myeditor.png

The application itself should be compiled for the architecture you intend to support. Most elementary OS desktop installations use x86_64, while some newer devices use ARM64. An AppImage is generally architecture-specific, so a 64-bit Intel or AMD bundle will not run on an ARM machine without emulation. If both audiences matter, publish separate files with clear names.

Build against an older, still-supported Linux environment rather than the newest distribution available. A binary linked against a very recent version of glibc may fail on an older elementary OS installation. Libraries supplied inside the AppImage can travel with the program, but core system components such as the kernel, graphics drivers, and often glibc still come from the host. Check release-specific compatibility information in the Freya Central guide before choosing the oldest system you plan to support.

For a graphical application, ensure that runtime assets use relative or predictable paths. A program that searches only /usr/share/myeditor may work after a conventional installation but fail inside an AppImage. Many frameworks expose an application directory variable or allow paths to be resolved relative to the executable. Test configuration files, translations, themes, plugins, and icon loading from the bundled location.

Assemble a valid AppDir

The desktop entry is the part that tells elementary OS how to display and launch the program. A basic file could contain:

[Desktop Entry]
Name=My Editor
Comment=Edit plain text files
Exec=myeditor %U
Icon=myeditor
Type=Application
Categories=Utility;TextEditor;
Terminal=false

The value in Exec should match the executable available through the AppImage's runtime path. %U allows the application to receive one or more URLs or files, although the program must be written to process those arguments correctly. If it cannot open files passed from the file manager, use Exec=myeditor instead.

Use a square PNG or SVG icon with the same name specified by Icon. Multiple PNG sizes provide better results in the applications menu and dock. Common sizes include 64, 128, 256, and 512 pixels. Avoid embedding a file extension in the Icon field unless a particular toolkit requires it.

The AppRun file can be a symbolic link to the main binary:

ln -s usr/bin/myeditor MyEditor.AppDir/AppRun

Alternatively, use a shell script when the application needs environment variables or a custom working directory:

#!/bin/sh
HERE="$(dirname "$(readlink -f "$0")")"
exec "$HERE/usr/bin/myeditor" "$@"

Save the script as AppRun and make it executable:

chmod +x MyEditor.AppDir/AppRun

A packaging tool can collect shared libraries and produce the final file. linuxdeploy is commonly used for this purpose, often with a desktop-file plugin and an icon plugin. A typical workflow resembles:

./linuxdeploy-x86_64.AppImage \
  --appdir MyEditor.AppDir \
  --executable MyEditor.AppDir/usr/bin/myeditor \
  --desktop-file MyEditor.AppDir/usr/share/applications/myeditor.desktop \
  --icon-file MyEditor.AppDir/usr/share/icons/hicolor/256x256/apps/myeditor.png \
  --output appimage

The exact options vary between tool versions. If the application uses Qt, GTK, GStreamer, Java, Electron, or another sizeable framework, inspect the resulting bundle rather than assuming every dependency was found. Some plugins are loaded dynamically and are invisible to a basic dependency scan.

Create and inspect the executable file

linuxdeploy can create an AppImage directly, but appimagetool is another common option. Once the AppDir is complete, run the packaging utility against it:

ARCH=x86_64 ./appimagetool-x86_64.AppImage MyEditor.AppDir

This should create a file such as MyEditor-x86_64.AppImage. Keep the filename descriptive. Include the application name, version, and architecture when distributing releases, for example myeditor-2.4.1-x86_64.AppImage.

Before sharing it, make the file executable and launch it from a terminal:

chmod +x MyEditor-2.4.1-x86_64.AppImage
./MyEditor-2.4.1-x86_64.AppImage

The terminal is useful because missing libraries, permission failures, and graphics problems often appear there first. A successful build that opens a window is only an initial check. Open files from the file manager, save to a different directory, test command-line arguments, select a desktop notification, and check whether settings persist after closing the program.

Some systems may report a FUSE-related error when mounting an AppImage. This can happen if FUSE support is absent, restricted, or configured differently on the host. Newer AppImage tools may offer extraction as a fallback, but that does not solve every runtime issue. Document the supported environment and test on the elementary OS releases your users actually run.

Test the bundle on a clean virtual machine or a separate user account with the development libraries removed. A machine used for compiling may hide missing resources because the required packages are already installed. Testing on both an up-to-date system and an older supported installation gives a more reliable picture of compatibility.

For users in Australia, a clean download process also matters on variable connections. NBN performance differs between suburbs and providers, and a large bundle can be inconvenient on a mobile hotspot in regional Queensland or Western Australia. Compress assets sensibly, avoid shipping unnecessary debug files, and publish the file size before download.

Add the AppImage to the applications menu

Running an AppImage from the Downloads directory works, but it does not provide the integration many elementary OS users expect. The file will not automatically appear in the applications menu simply because it has a desktop entry inside the bundle. The desktop entry must be placed where the current user’s desktop environment can find it.

A manual per-user integration process can use these commands:

mkdir -p ~/.local/share/applications
mkdir -p ~/.local/share/icons/hicolor/256x256/apps

cp MyEditor.AppDir/usr/share/applications/myeditor.desktop \
   ~/.local/share/applications/

cp MyEditor.AppDir/usr/share/icons/hicolor/256x256/apps/myeditor.png \
   ~/.local/share/icons/hicolor/256x256/apps/

Edit the copied desktop file so that Exec points to the permanent AppImage location, not to a temporary build directory. For example:

Exec=/home/alex/Applications/MyEditor-2.4.1-x86_64.AppImage %U
Icon=/home/alex/.local/share/icons/hicolor/256x256/apps/myeditor.png

Absolute icon paths are straightforward, although a named icon installed in the local icon theme is cleaner. The user must also keep the AppImage in the same location. Moving or deleting it will leave a broken menu entry.

An integration utility can automate this process. Tools such as AppImageLauncher offer a prompt to move an AppImage into a chosen applications directory and create a menu entry. Other desktop integration tools may add update handling or a right-click option. Review what a tool changes before accepting it, especially when installing software from an unfamiliar source.

After copying a desktop file, the menu cache may update automatically. If the application does not appear, log out and back in, restart the desktop shell if applicable, and inspect the file for syntax errors. The desktop entry must have a .desktop extension, correct permissions, a valid Type=Application line, and an executable path that still exists.

For a removable or portable setup, keep the AppImage and its icon together in a folder under ~/Applications. This makes backup and removal easier. To uninstall the integrated application, delete the AppImage, its desktop entry, and any separately installed icon. No package database cleanup should be necessary.

Improve security, updates, and distribution

An AppImage has no built-in guarantee that its contents are trustworthy. Users should download it from the project’s official website or release repository, verify a published SHA-256 checksum, and prefer a cryptographic signature when one is available. Developers should publish checksums over a trusted channel and explain which file each checksum belongs to.

Avoid telling users to run a downloaded file with sudo. An AppImage normally needs only user-level permissions. Administrative execution increases the damage a compromised or poorly designed application could cause. Remember that an AppImage is not a sandbox; once launched, the program may be able to read or modify files available to the user.

Updates can be handled in several ways. A project may provide a new download for every release, use an AppImage update mechanism, or connect the application to its own update service. The simplest approach is often the clearest: show the current version inside the program, provide release notes, and make older files easy to identify. Never replace a user’s local file without explaining where the new version came from.

Applications that access online accounts, documents, or telemetry need a clear privacy policy. This is relevant to Australian users under the Privacy Act where an organisation falls within its coverage and handles personal information. Software sold or promoted to Australian consumers should also use accurate pricing and product claims, and commercial developers should consider obligations under the Australian Consumer Law. GST treatment can depend on the business and transaction, so pricing in Australian dollars should be presented carefully rather than implied through a rough currency conversion.

Distribution pages should state supported architectures, minimum elementary OS or Linux requirements, file size, license, source-code location where applicable, and known limitations. If the project has users in Sydney, Melbourne, Adelaide, or smaller regional centres, clear troubleshooting information is often more useful than assuming everyone has the same hardware, graphics stack, or internet provider.

Diagnose common launch and menu failures

A file that refuses to launch is often missing executable permission. Check it with:

ls -l MyEditor-2.4.1-x86_64.AppImage

The permission string should contain an x, such as -rwxr-xr-x. If it does not, run chmod +x again. A filesystem mounted with the noexec option can also block execution. Moving the file to a normal location under the user’s home directory can help identify that problem.

If the application opens and immediately closes, run it from a terminal and inspect its output. Missing shared libraries, an invalid plugin path, an incompatible graphics driver, and incorrect working-directory assumptions are common causes. Use ldd on the bundled executable for an initial dependency check, while remembering that libraries loaded dynamically may not appear in the output.

A blank or missing icon usually indicates a mismatch between the desktop entry and the installed icon name. Confirm that the icon file exists, that the desktop file uses the correct Icon value, and that the image format is supported. A malformed desktop file can be checked with desktop-entry validation tools available from many Linux repositories.

File associations require extra care. To open a text file with the AppImage, the desktop entry needs a matching MimeType declaration, such as text/plain;, followed by a desktop database refresh when required. The application must also accept the path passed through %F or %U. Without both pieces, the menu entry may work while double-clicking a document does not.

When reporting a problem in an elementary OS community forum, include the elementary OS version, hardware architecture, AppImage version, terminal output, and the exact command used. Do not paste private tokens, account details, or documents into a public post. That information makes it easier to distinguish a packaging error from a host-system issue.

A dependable AppImage is more than a file with execute permission. It has a deliberate directory structure, a compatible dependency strategy, a correct desktop entry, a recognisable icon, safe distribution practices, and a tested removal path. Build for the oldest supported environment, verify the bundle on a clean elementary OS system, and integrate it through the user’s local applications directory. The key point to remember is that portability comes from careful packaging, while a native-feeling elementary OS experience comes from equally careful desktop integration.