Python Flatpak Packaging — Core Concepts

What Flatpak is

Flatpak is a Linux application packaging and distribution framework focused on desktop applications. It provides sandboxing (via bubblewrap and namespaces), shared runtimes (to avoid bundling common libraries), and a repository system for distribution.

For Python developers, Flatpak is the standard way to ship GUI applications (GTK, Qt, Tkinter) to Linux desktops across all distributions.

How Flatpak differs from snaps

Both Flatpak and Snap solve similar problems, but with different philosophies:

Aspect	Flatpak	Snap
Focus	Desktop applications	Desktop + server + IoT
Runtime model	Shared runtimes (GNOME, KDE)	Each snap bundles everything
Store	Flathub (community-driven)	Snap Store (Canonical-controlled)
Sandbox	Portals-based permissions	AppArmor-based confinement
Distribution support	All major Linux distros	Ubuntu-native, others via snapd
Disk usage	Lower (shared runtimes)	Higher (self-contained)

The manifest file

Flatpak builds are configured through a JSON or YAML manifest:

{
    "app-id": "com.example.MyPythonApp",
    "runtime": "org.gnome.Platform",
    "runtime-version": "45",
    "sdk": "org.gnome.Sdk",
    "command": "my-python-app",
    "finish-args": [
        "--share=network",
        "--share=ipc",
        "--socket=fallback-x11",
        "--socket=wayland",
        "--device=dri"
    ],
    "modules": [
        {
            "name": "python-requests",
            "buildsystem": "simple",
            "build-commands": [
                "pip3 install --prefix=/app --no-deps ."
            ],
            "sources": [
                {
                    "type": "archive",
                    "url": "https://files.pythonhosted.org/packages/.../requests-2.31.0.tar.gz",
                    "sha256": "..."
                }
            ]
        },
        {
            "name": "my-python-app",
            "buildsystem": "simple",
            "build-commands": [
                "pip3 install --prefix=/app --no-deps .",
                "install -Dm644 data/icon.svg /app/share/icons/hicolor/scalable/apps/com.example.MyPythonApp.svg",
                "install -Dm644 data/com.example.MyPythonApp.desktop /app/share/applications/com.example.MyPythonApp.desktop"
            ],
            "sources": [
                {
                    "type": "dir",
                    "path": "."
                }
            ]
        }
    ]
}

Runtimes and SDKs

Flatpak uses shared runtimes — pre-built base environments that include common libraries:

• org.gnome.Platform / org.gnome.Sdk — GTK, GLib, Python 3, and GNOME libraries.
• org.kde.Platform / org.kde.Sdk — Qt, KDE Frameworks libraries.
• org.freedesktop.Platform / org.freedesktop.Sdk — minimal base with just the essentials.

The GNOME runtime already includes Python 3 and many common libraries, so your Flatpak only needs to bundle Python packages not in the runtime.

# Install the GNOME runtime
flatpak install flathub org.gnome.Platform//45
flatpak install flathub org.gnome.Sdk//45

Building the Flatpak

# Install flatpak-builder
sudo apt install flatpak-builder

# Build and install locally
flatpak-builder --user --install --force-clean build-dir com.example.MyPythonApp.json

# Run the app
flatpak run com.example.MyPythonApp

The build happens in a sandboxed environment. flatpak-builder downloads sources, runs build commands, and packages the result.

Python dependency management

Each Python dependency needs its own module entry in the manifest. This gets tedious for many dependencies. The flatpak-pip-generator tool automates it:

# Generate manifest entries from requirements
pip install flatpak-pip-generator
flatpak-pip-generator requests click pydantic

# Output: python3-requests.json, python3-click.json, etc.
# Include these in your manifest

Or generate from a requirements file:

flatpak-pip-generator --requirements-file requirements.txt --output pypi-deps

This generates a JSON file you can include in your manifest’s modules list.

Sandbox permissions

Flatpak uses a fine-grained permission system through finish-args:

"finish-args": [
    "--share=network",              // Network access
    "--share=ipc",                  // Inter-process communication
    "--socket=wayland",             // Wayland display
    "--socket=fallback-x11",        // X11 fallback
    "--filesystem=home:ro",         // Read-only home directory access
    "--filesystem=/tmp",            // Full /tmp access
    "--talk-name=org.freedesktop.Notifications",  // Desktop notifications
    "--device=dri"                  // GPU access (OpenGL)
]

For file access, Flatpak uses portals — the app requests access through a system dialog, and the user grants it per-file. This is more secure than blanket filesystem access.

Desktop integration files

Flatpak apps need three files for proper desktop integration:

Desktop entry:

# com.example.MyPythonApp.desktop
[Desktop Entry]
Type=Application
Name=My Python App
Comment=A useful desktop application
Icon=com.example.MyPythonApp
Exec=my-python-app %f
Categories=Utility;

AppStream metadata (for Flathub listing):

<!-- com.example.MyPythonApp.metainfo.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop-application">
  <id>com.example.MyPythonApp</id>
  <name>My Python App</name>
  <summary>A useful desktop application</summary>
  <description>
    <p>Longer description for the Flathub store page.</p>
  </description>
  <url type="homepage">https://example.com</url>
  <releases>
    <release version="1.0.0" date="2026-03-28"/>
  </releases>
</component>

Icon: SVG preferred, installed to the standard icon path.

Common misconception

“Flatpak is only for GNOME applications.”

While Flatpak was started by GNOME developers and integrates deeply with GNOME, it works for any Linux desktop application. Qt/KDE apps use the org.kde.Platform runtime. Electron apps, terminal apps, and even CLI tools can be packaged as Flatpaks. The KDE community actively maintains Flatpak packages for their applications.

One thing to remember: Flatpak gives Python desktop applications a professional distribution path — shared runtimes keep packages small, the sandbox keeps users safe, and Flathub provides a trusted storefront that reaches every major Linux distribution.