Publishing your Python app as a Flatpak

Ship your app easily to users.

Creating a Flatpak

We can also take care of distributing our PyQt application. Although the Python Package Index (PyPI) is probably the standard way to distribute a Python package, Flatpak should be more user friendly for Linux users than using command line tools such as pip.

Flatpaks are built locally using flatpak-builder. The tool checks out the source code and any of its custom dependencies, then builds it against a runtime (a collection of libraries shared between flatpaks). Since we already took care of the source code, all we need is to write a single file, the flatpak manifest, which describes everything needed to build the package.

Create a new flatpak manifest file simplemdviewer/org.kde.simplemdviewer.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
{
    "id": "org.kde.simplemdviewer",
    "runtime": "org.kde.Platform",
    "runtime-version": "6.7",
    "sdk": "org.kde.Sdk",
    "base": "io.qt.PySide.BaseApp",
    "base-version": "6.7",
    "command": "simplemdviewer",
    "finish-args": [
    "--share=ipc",
    "--socket=fallback-x11",
    "--socket=wayland",
    "--device=dri",
    "--socket=pulseaudio"
    ],
    "modules": [
        "python3-markdown.json",
        {
            "name": "simplemdviewer",
            "buildsystem" : "simple",
            "build-commands" : [
                "pip3 install --no-build-isolation --prefix=/app ."
            ],
            "sources": [
                {
                    "type": "archive",
                    "path": "dist/org_kde_simplemdviewer-0.1.tar.gz"
                }
            ]
        }
    ],
    "cleanup-commands": [
        "/app/cleanup-BaseApp.sh"
    ]
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "id": "org.kde.simplemdviewer",
    "runtime": "org.kde.Platform",
    "runtime-version": "6.7",
    "sdk": "org.kde.Sdk",
    "base": "com.riverbankcomputing.PyQt.BaseApp",
    "base-version": "6.7",
    "command": "simplemdviewer",
    "finish-args": [
    "--share=ipc",
    "--socket=fallback-x11",
    "--socket=wayland",
    "--device=dri",
    "--socket=pulseaudio"
    ],
    "modules": [
        "python3-markdown.json",
        {
            "name": "simplemdviewer",
            "buildsystem" : "simple",
            "build-commands" : [
                "pip3 install --no-build-isolation --prefix=/app ."
            ],
            "sources": [
                {
                    "type": "archive",
                    "path": "dist/org_kde_simplemdviewer-0.1.tar.gz"
                }
            ]
        }
    ]
}

This file reads that we use the markdown module and the build info is provided by the python3-markdown.json manifest file. We are going to create this manifest automatically using flatpak-pip-generator.

Download flatpak-pip-generator, and save it into the simplemdviewer/env/bin/ directory:

wget https://raw.githubusercontent.com/flatpak/flatpak-builder-tools/master/pip/flatpak-pip-generator --directory-prefix env/bin

The generator has a single dependency to run, requirements-parser. After installing it in the virtual environment, the tool can be run:

python3 -m pip install requirements-parser
python3 env/bin/flatpak-pip-generator markdown

You should see a new python3-markdown.json inside simplemdviewer/ now.

We are using the KDE Runtime, which provides Qt dependencies like QtQuick and KDE frameworks like Kirigami, so you will need the Software Development Kit (Sdk) runtime to build the app locally, and the Platform runtime to run it. More than that, the KDE Runtime is based on the general Freedesktop Runtime, which provides Python. You can read more about runtimes in the Flatpak Runtime Documentation.

Install org.kde.Sdk and org.kde.Platform, version 6.7, from Flathub:

flatpak install org.kde.Platform/x86_64/6.7 org.kde.Sdk/x86_64/6.7

For a PyQt Flatpak application, we are using the PyQt Baseapp, which contains an already built and ready-to-use PyQt we can quickly add on top of the KDE Runtime, so we need to install it as well. Alternatively, you can use the PySide Baseapp, which provides a similar ready-to-use PySide6 environment.

flatpak install io.qt.PySide.BaseApp/x86-64/6.7
flatpak install com.riverbankcomputing.PyQt.BaseApp/x86-64/6.7

To attempt a first build of the flatpak, run:

flatpak-builder --force-clean flatpak-build-dir org.kde.simplemdviewer.json

Test the flatpak build:

flatpak-builder --run flatpak-build-dir org.kde.simplemdviewer.json simplemdviewer

Build a distributable nightly flatpak bundle:

flatpak-builder --repo simplemdviewer-master --force-clean --ccache flatpak-build-dir org.kde.simplemdviewer.json
flatpak build-bundle simplemdviewer-master simplemdviewer.flatpak org.kde.simplemdviewer

Now we can either distribute the simplemdviewer.flatpak directly to the users, or submit the application to a flatpak repository, like the most popular repository, Flathub. See the App Submission Guidelines.

Other improvements you can make to your application:

Happy hacking.