Mastering AppImages: A Step-by-Step Guide to Building and Distributing Cross-Platform Applications

Mastering AppImages: A Step-by-Step Guide to Building and Distributing Cross-Platform Applications


4 min read

๐Ÿ“” Introduction

The repository used for this article is this

AppImage is a format for distributing portable software on Linux without needing superuser permissions to install the application. It tries also to allow Linux distribution-agnostic binary software deployment for application developers, also called upstream packaging. Released first in 2004 under the name klik, it was continuously developed, then renamed in 2011 to PortableLinuxApps and later in 2013 to AppImage.


๐Ÿงฐ Prerequisites

Since AppImages are for unix/linux systems most of them come with what we are going to use today, but here is what i'm using in this tutorial

  • curl

  • git

  • make

  • python3

๐Ÿ“ Creating the AppImage Structure

  • This is the final structure of my AppImage

  • We are mostly going to work inside src, and AppRun

  • I've tried to build this as simple as possible to not modify more than just 2 files then do your thing

 โ”ฃ ๐Ÿ“‚usr
 โ”ƒ โ”ฃ ๐Ÿ“‚build
 โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“œappimagetool-x86_64.AppImage
 โ”ƒ โ”ƒ โ”— ๐Ÿ“œfacts-x86_64.AppImage
 โ”ƒ โ”ฃ ๐Ÿ“‚src
 โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“‚__pycache__
 โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“‚utils
 โ”ƒ โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“‚__pycache__
 โ”ƒ โ”ƒ โ”ƒ โ”— ๐Ÿ“œ
 โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“œ
 โ”ƒ โ”ƒ โ”ฃ ๐Ÿ“œ
 โ”ƒ โ”ƒ โ”— ๐Ÿ“œ
 โ”ƒ โ”ฃ ๐Ÿ“œ.DirIcon
 โ”ƒ โ”ฃ ๐Ÿ“œ.appimageignore
 โ”ƒ โ”ฃ ๐Ÿ“œ.gitignore
 โ”ƒ โ”ฃ ๐Ÿ“œAppRun
 โ”ƒ โ”ฃ ๐Ÿ“œMakefile
 โ”ƒ โ”ฃ ๐Ÿ“œ
 โ”ƒ โ”ฃ ๐Ÿ“œ
 โ”ƒ โ”ฃ ๐Ÿ“œfacts.desktop
 โ”ƒ โ”— ๐Ÿ“œimage.png
 โ”ฃ ๐Ÿ“œMakefile
 โ”ฃ ๐Ÿ“œ
 โ”— ๐Ÿ“œ

๐Ÿงฐ The

  • This is the main file that contains most of the configuration

  • I've left a comment to know each of the variables he has her


  • do not leave spaces at the end

  • fill all the fields

  • do not include extensions for the image

# This is the name of your application
# This is the folder where your main file is located
# Name of your icon located inside the usr folder
# Category of your application for more read
# Version of your application
# Name of your .desktop file

๐Ÿ„ The Makefile

A makefile is a file containing a set of directives used by a make build automation tool to generate a target/goal.


In our example, we have 2 makefiles one at the root level and one inside the usr folder, this structure is not really necessary you can work everything inside usr I've just found this more flexible to work under a Github repository

include does what it says, includes variables from our

Now the build: clean desktop is a more interesting one because it does what it says below which is moving into the usr folder and running another make command there, but before doing that it runs clean and desktop as dependencies if there is an error with clean or desktop the build command won't run. So with that in mind I think is pretty straightforward.

# Inside the `usr` folder is another Makefile with detailed instructions about what does each command
# This is just a wrapper to make it easier to use
# Built by @jd-apprentice


build: clean desktop
    cd usr && make build

    cd usr && make prepare

    cd usr && make run-dev

    cd usr && make clean

    cp usr/

    sudo rm -rf /usr/local/bin/"$(NAME)"

start: copy
    cd usr && make start

    echo "[Desktop Entry]\nName=$(NAME)\nIcon=$(ICON)\nType=Application\nCategories=$(CATEGORY)\nTerminal=true\nX-AppImage-Version=$(VERSION)" > ./usr/$(DESKTOP)

๐Ÿ‘Ÿ The AppRun

This file is our main executable for your application so if you are running a Python app like myself I'll have to do it something like this


cd "$(dirname "$0")"
python3 ./src/

โญ Let's run our application

I've explained all of this just to get you in touch a little bit about my format of building the AppImage and how they work with each of the files but for this example we only have to do the following:

make build

We know is working because it gently asks us to upload your app to their directory (I'll explain in another article)

And now to run it

make start

With this, we can see that our AppImage was created (this only fetches random facts from an API and prints them)

๐Ÿ Conclusion

With this approach we work like would normally do inside src folder

Modify the AppRun and the then use the Makefile to build and run everything and we are set! Enjoy your AppImage! ๐Ÿ˜

Did you find this article valuable?

Support Jonathan by becoming a sponsor. Any amount is appreciated!