Python AppImages

We provide relocatable Python runtimes for Linux systems, as AppImages. These runtimes have been extracted from manylinux Docker images.

Basic installation

Installing Python from an AppImage is as simple as downloading a single file and changing its mode to executable. For example, as

wget https://github.com/niess/python-appimage/releases/download\
/python3.10/python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage

chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage

Note

As can be seen from the previous example, the AppImage name contains several informations. That are, the Python full version (3.10.2), the CPython tag (cp310-cp310), the Linux compatibility tag (manylinux2014) and the machine architecture (x86_64).

Caution

One needs to select an AppImage that matches system requirements. A summmary of available Python AppImages is provided at the bottom of this page.

Since AppImages native names are rather lengthy, one might create a symbolic link, e.g. as

Then, executing the AppImage as ./python3.10 should start a Python interactive session on almost any Linux, provided that fuse is supported.

Tip

Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing AppImages direct execution. Yet, one can still extract the content of Python AppImages and use them, as explained in the Advanced installation section.

Installing site packages

Site packages can be installed using pip, distributed with the AppImage. For example, the following

./python3.10 -m pip install numpy

installs the numpy package, where it is assumed that a symlink to the AppImage has been previously created. When using the basic installation scheme, by default Python packages are installed to your user space, i.e. under ~/.local on Linux.

Note

AppImage are read-only. Therefore, site packages cannot be directly installed to the AppImage. However, the AppImage can be extracted, as explained in the Advanced installation section.

Alternative site packages location

One can specify an alternative installation directory for site packages using the --target option of pip. For example, the following

./python3.10 -m pip install --target=$(pwd)/packages numpy

installs the numpy package besides the AppImage, in a packages folder.

Tip

Packages installed in non standard locations are not automatically found by Python. Their location must be aded to sys.path, e.g. using the PYTHONPATH environment variable.

Caution

While Python AppImages are relocatable, site packages might not be. In particular, packages installing executable Python scripts assume a fix location of the Python runtime. If the Python AppImage is moved, then these scripts will fail. This can be patched by editing the script shebang, or be reinstalling the corresponding package.

Isolating from the user environment

By default, Python AppImages are not isolated from the user environment. For example, packages located under ~/.local/lib/pythonX.Y/site-packages are loaded prior to AppImage's (system) ones. Note that this is the usual Python runtime behaviour. However, it can be conflictual for some applications.

In order to isolate your application from the user environment, the Python runtime provides the -E, -s and -I options. For example, invoking a Python AppImage as ./python3.10 -s prevents the loading of user site packages (located under ~/.local). Additionaly, the -E option disables Python related environment variables. In particular, it prevents packages under PYTHONPATH to be loaded. The -I option triggers both -E and -s.

Using a virtual environement

Isolation can also be achieved with a virtual environment. Python AppImages can create a venv using the standard syntax, e.g. as

./python3.10 -m venv /path/to/new/virtual/environment

Note that moving the base Python AppImage to another location breaks the virtual environment. This can be patched by editing symbolic links under venv/bin, as well as the home variable in venv/pyvenv.cfg. The latter must point to the AppImage directory.

Tip

Old Python AppImages, created before version 1.1, fail setting up pip automaticaly during venv creation. However, this can be patched by calling ensurepip from within the venv, after its creation. For example, as

source /path/to/new/virtual/environment/bin/activate

python -m ensurepip

Advanced installation

The basic installation scheme described previously has some limitations when using Python AppImages as a runtime. For example, site packages need to be installed to a separate location. This can be solved by extracting a Python AppImage to an *.AppDir directory, e.g. as

./python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage --appimage-extract

mv squashfs-root python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir

ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10

Then, by default site packages are installed to the extracted AppDir, when using pip. In addition, executable scripts installed by pip are patched in order to use relative shebangs. Consequently, the AppDir can be freely moved around.

Note

Python AppDirs follow the manylinux installation scheme. Executable scripts are installed under AppDir/opt/pythonX.Y/bin where X and Y in pythonX.Y stand for the major and minor version numbers. Site packages are located under AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages. For convenience, pip installed applications are also mirrored under AppDir/usr/bin, using symbolic links.

Tip

As for Python AppImages, by default the extracted runtime is not isolated from the user environment. This behaviour can be changed by editing the AppDir/usr/bin/pythonX.Y wrapper script, and by adding the -s, -E or -I option at the very bottom, where Python is invoked.

Repackaging the AppImage

An extracted AppDir can be re-packaged as an AppImage using appimagetool, e.g. as

wget https://github.com/AppImage/AppImageKit/releases/download/continuous/\
appimagetool-x86_64.AppImage

chmod +x appimagetool-x86_64.AppImage

./appimagetool-x86_64.AppImage \
    python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir \
    python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage

This allows to customize your Python AppImage, for example by adding your preferred site packages.

Note

Python AppImages can also be used for packaging Python based applications, as AppImages. Additional details are provided in the developers section.

Available Python AppImages

A summary of available Python AppImages releases is provided in the table below. Clicking on a badge should download the corresponding AppImage.

Caution

According to your browser, your system would not be compatible with Python Appimages.