Developers' corner

Python AppImages are created using the python-appimage utility, which is available on PyPI. This utility can also be used to package Python-based applications as AppImages using an existing AppImage and a recipe folder.

Building a Python AppImage

The primary purpose of python-appimage is to relocate an existing Python installation to an AppDir and build the corresponding AppImage. For example, the command

python-appimage build local -p $(which python2)

should create an AppImage of your local Python installation, provided that it exists.

python-appimage which appimagetool

Manylinux Python AppImages

AppImages of your local python are unlikely to be portable, unless you are running an outdated Linux distribution. A core component that prevents portability across Linux distributions is the use of different versions of the glibc system library. Fortunately, glibc is highly backward compatible. Therefore, a simple workaround is to compile binaries using the oldest Linux distribution you can. This strategy is used to create portable AppImages and to distribute Python site packages as ready-to-use binary wheels.

The Python Packaging Authority (PyPA) has defined standard platform tags for building Python site packages labelled Manylinux. These build platforms are available as Docker images, with different versions of Python already installed. The python-appimage utility can be used to package these installations as AppImages. For example, the following command

python-appimage build manylinux 2014_x86_64 cp313-cp313

should build an AppImage of Python 3.13 using the CPython (cp313-cp313) installation found in the manylinux2014_x86_64 Docker image.

Simple packaging

The python-appimage utility can also be used to package simple AppImage applications, whose dependencies can be installed using pip. The syntax is

python-appimage build app -p 3.13 /path/to/recipe/folder

to build a Python 3.13-based application from a recipe folder. Examples of recipes can be found in the applications folder on GitHub. The recipe folder contains

• the AppImage metadata (application.xml and application.desktop),
• an application icon (e.g. application.png),
• a Python requirements file (requirements.txt),
• an entry point script (entrypoint.sh).

Further information on metadata can be found in the AppImage documentation (e.g., regarding desktop and AppStream XML files). The requirements.txt file enables additional site packages to be specified for bundling in the AppImage using pip.

{{ python-executable }} ${APPDIR}/opt/python{{ python-version }}/bin/my_app.py "$@"

Bundling data files

python-appimage is also capable of bundling auxiliary data files directly into the resulting AppImage. The -x/--extra-data switch is used for this purpose. Consider the following example.

echo -n "foo" > foo
mkdir bar
echo -n "baz" > bar/baz
python-appimage [your regular parameters] -x foo bar/*

In this way, user data becomes accessible to the Python code contained within the AppImage as regular files under the directory pointed to by the APPDIR environment variable. An example of a Python 3 script that reads these files is presented below.

import os, pathlib
for fileName in ("foo", "baz"):
  print((pathlib.Path(os.getenv("APPDIR")) / fileName).read_text())

When executed, the above code would produce the following output.

foo
baz

Advanced packaging

In more complex cases, for example if your application relies on external C libraries that are not bundled with the Python runtime, the simple packaging scheme described previously will not work. This falls outside the scope of python-appimage, which is primarily intended for relocating an existing Python installation. In this case, you may wish to refer to the initial AppImage Packaging Guide, and use alternative tools such as linuxdeploy.

However, python-appimage can still be useful in more complex cases, as it can generate a base AppDir containing a relocatable Python runtime (e.g., using the -n option). This can then serve as a starting point to create more complex AppImages.