Creating AppImages

The general workflow for creating an AppImage involves the following steps:

  1. Gather suitable binaries If the application has already been compiled, you can use existing binaries (for example, contained in .tar.gz, deb, or rpm archives). Note that the binaries must not be compiled on newer distributions than the ones you are targeting. In other words, if you are targeting Ubuntu 9.10, you should not use binaries compiled on Ubuntu 10.04.

  2. Gather suitable binaries of all dependencies that are not part of the base operating systems you are targeting. For example, if you are targeting Ubuntu, Fedora, and openSUSE, then you need to gather all libraries and other dependencies that your app requires to run that are not part of Ubuntu, Fedora, and openSUSE.

  3. Create a working AppDir from your binaries. A working AppImage runs your app when you execute its AppRun file.

  4. Turn your AppDir into an AppImage. This compresses the contents of your AppDir into a single, self-mounting and self-executable file.

  5. Test your AppImage on all base operating systems you are targeting. This is an important step which you should not skip. Subtle differences in distributions make this a must. While it is possible in most cases to create AppImages that run on various distributions, this does not come automatically, but requires careful hand-tuning.

While it would theoretically be possible to do all these steps by hand, AppImageKit contains tools that greatly simplify the tasks.

Most of the time, the software you would like to package as an AppImage has already been packaged for one of the commonly used distributions. At the time of this writing, most software was available for Ubuntu (including software in personal package archives, PPAs) and other repositories. If your app is already available there (and chances are), then it is especially straightforward to create an AppImage using the tools contained in the AppImageKit.

  1. Run the version of Ubuntu that you are targeting, or an older version. Do not run a newer version of Ubuntu than the one you are targeting, or your AppImage will likely not run on the targeted version. It is recommended to run from the official Ubuntu Live CD (or Live USB) system, since this is guaranteed to be in a known default state.

  2. If your software is available in a PPA or other third-party repository, add the repository to the system (by editing /etc/apt/sources.list or by using add-apt-repository).

  3. Run sudo apt-get update to refresh the package information.

  4. Run create-appimage. For example, if you would like to create an AppImage of gnubik, run create-appimage gnubik. This is similar to running apt-get install gnubik; however, instead of installing the app to your system it creates an AppImage of your app. Note that the AppImage contains gnubik.desktop and AppRun.

    Note

    create-appimage automatically fetches dependencies that are not part of your current operating system installation. This is possibly not enough to satisfy all dependencies that are not part of all the distributions that you are targeting. Hence, you might have to copy some additional dependencies into your AppDir manually, until it runs on all the distributions that you are targeting.

    Note

    create-appimage automatically patches the binaries in your AppImage so that the absolute path /usr is replaced with the relative path ././ (which simply means "here"), effectively making the binaries relocateable. While this is sufficient for most C/C++ apps, it might not be sufficient for apps using some higher-level frameworks such as Perl, Python, C#, etc. In this case, you have to adjust your app manually until it runs from any location ("relocateable").

  5. Double-click AppRun. The gnubik app should run. The gnubik.desktop file tells AppRun which executable should be executed. You could also try coping your AppDir to the other systems targeted, like Fedora and openSUSE, and check whether your app runs there as well. However, this step will be done (with great simplification) later on.

    Note

    If your app does not run when you double-click the AppRun file, then you need to fix this first before you can progress to making an AppImage out of the AppDir. The strace command can be helpful in determining files that cannot be found by the app (e.g., strace -eopen -f ./AppRun 2>&1 | grep ENOENT gives you all the files that are tried to be opened but not found).

  6. Run AppImageAssistant and select the gnubik.AppDir/ that you just created. AppImageAssistant will guide you through the process of creating the AppImage. In the process, it checks whether your gnubik.desktop file has all the necessary information, whether the icon is available, and whether the executable specified in the gnubik.desktop file can be found in the gnubik.AppDir/usr/bin directory.

    Note

    If the icon is not found, make sure that you have a 48x48 pixel png file called gnubik.png either in gnubik.AppDir/ or in the appropriate gnubik.AppDir/usr/share/icons/... subdirectory (as per the Desktop File Specification).

  7. At the end of the AppImageAssistant, you will be prompted to run your AppImage in various test environments, such as the targeted versions of Ubuntu, Fedora, and openSUSE. AppImageAssistant runs your AppImage in a special chroot environment based on each distribution's Live CD image.

    Be sure not to release an AppImage that you have not tested on each of the distributions you are targeting. While it is reasonably safe to assume that later versions of the distributions you have tested will still run your AppImage (at least if they are carefully designed), it is not safe to assume that other distributions will do so, too.

    Note

    For this to work, you need to prepare squashfs images of the targeted base operating systems. Instructions on how to do this can be found at http://portablelinuxapps.org/forum.

  8. Optionally, if you would like to distribute your AppImage to your users, rename it to "AppName Version", e.g., "GNUbik 1.0" and put it up for download. Please do not put the AppImage inside a compressed archive, since it is already compressed by itself.

  9. Optionally, if you would like to get comments on your AppImage and/or suggest it for inclusion on PortableLinuxApps, a website dedicated to AppImages that run on Ubuntu, Fedora, and openSUSE, then create a posting in the "Labs" area of http://portablelinuxapps.org/forum

If your software has not yet been packaged for Ubuntu (or if you simply like doing things "from scratch"), then you can create your AppDir manually. In that case, replace steps 1-4 above with: