Introducing Flatpak Builds

Flatpak is a software for building, installing and running Linux apps. The runtime offers a sandbox with restricted permissions. Each app comes as a bundle, and while two different apps can depend on different versions of the same dependency, they can run isolated from each other in parallel.

OBS now supports building flatpak bundles, so you can build your own!

Quick Start

Even if you have never built a flatpak app, you can quickly make your first step by branching the Template package. This will provide you with an already preconfigured project and package.

  1. Go to ImageTemplates
  2. Select “Template for Flatpak”
  3. Enter a name and click “Create”


  1. Go to FlatpakTemplate
  2. Click on “Actions -> Branch package”
  3. Click on the “Branch” button

After creating the package, OBS will start building. This can take a while.

When OBS finished publishing, you will find a .flatpak file in your folder under

Download the file and install it:

flatpak install --user org.gnome.Mahjongg-3.36.2.flatpak

You built and installed your first flatpak app!


This will be documented soon at our OBS package formats page.

For a successful Flatpak build you need four things:

  • The project configuration. Example
  • The project meta configuration. Example
  • A flatpak manifest file flatpak.yaml. Example
  • The sources mentioned in the manifest in form of tar archives


For the configuration you can simply copy from or branch the Template package.


The manifest file should be called flatpak.yaml. You can find a detailed reference at the official documentation.

Because Flatpak manifests don’t have a version field, and our downloadable files should have a version number, you can add a special #!BuildVersion field, ideally at the top of the YAML file. It is not required, but if you leave it out, you will always get version 0.

#!BuildVersion: 3.14.15
app-id: org.gnome.Mahjongg
runtime: org.gnome.Platform
sdk: org.gnome.Sdk
runtime-version: '3.36'
# etc.

How Does the Build Work?

OBS is not a replacement for Flathub, so we had to find a solution for providing the basic dependencies.

To make this work, we are installing the several platform images and SDKs in a container, tar the files together and create RPM packages from that.

This way they can be fetched as dependencies like in other builds. The correct platform/SDK and version is parsed from the manifest file. Parsing is done by the Build::Flatpak module.


Here are some screenshots of the project creation via ImageTemplates:

Image Templates
Image Templates
Create new project from Image Templates
Created new project from Image Templates
Build results
Build results

How To Give Us Feedback

There are two ways to reach us:

Please note that we favor GitHub to gather feedback as it allows us to easily keep track of the discussions.