How to create a Flatpak package step by step in Linux

If you work with GNU/Linux and are interested in distributing your applications in a simple way, sooner or later you will come across Flatpak. This packaging format has become one of the most popular ways to deliver desktop applications. that work the same on almost any distribution, without struggling with dependencies or the package manager of the day.

In this guide we will see How to create a Flatpak package step by step, from scratch and in great detailYou'll see exactly what Flatpak is, why it's so important today, what you need to prepare in your environment, how to structure your package, what metadata you need, how to install it, test it, export it to a repository, and even what it means to upload it to Flathub. All with a practical approach and in an accessible style so you don't find it overwhelming.

What is Flatpak and why has it become so important?

Flatpak is a container-based software packaging and distribution technology for LinuxThe idea is very simple but powerful: instead of depending on each distribution's package manager, the application is packaged along with the libraries and dependencies it needs, and runs in an isolated environment (sandbox) that guarantees consistent behavior on any compatible distro.

In practice, A Flatpak package includes the application and all the libraries necessary for it to function.without interfering with the rest of the system's programs. This avoids the classic dependency hell, reduces conflicts, and gives the developer direct control over how their application is distributed and updated, without having to wait for a distribution maintainer to package it.

To achieve this, Flatpak relies on shared runtime environmentsThese runtimes provide a common foundation (for example, a specific version of the GNOME platform) on which multiple applications run. This way, you don't have to package absolutely everything in each app, but only what isn't already included in the runtime, saving space and simplifying maintenance.

Furthermore, Flatpak applications run on a sandbox with its own permissions systemThis model allows you to control access to resources such as the file system, network, Bluetooth, audio, or the graphics server (X11/Wayland). Isolation improves security and limits the potential damage from a malicious or corrupted application.

One of the great advantages for users and administrators is that Flatpak packages are installed and updated independently of the distribution's package manager.You can have your Flatpak applications coexisting with native packages without them interfering with each other, and even manage multiple versions of the same app simultaneously.

Advantages and disadvantages of Flatpak compared to other formats

The GNU/Linux ecosystem has always had multiple packaging systems: deb, rpm, AppImage, Snap, Flatpak… Each one solves the problem of software distribution in their own way. Flatpak excels especially on the desktop, and it's no coincidence that many major distributions support it by default.

Among the main Advantages of Flatpak from the user's point of view can include:

• Simple and universal installation: With a single package format you can install the same app on different distributions (Debian, Fedora, openSUSE, Arch, etc.) as long as they have Flatpak enabled.
• Improved insulation and security: The applications run in a sandbox with explicit permissions, reducing risks and conflicts between programs.
• Automatic and centralized updates: With one command you can update all your apps Flatpak, without depending on the distro cycle.
• Coexistence of multiple versions: It is possible to have more than one version of the same application installed, which is very useful for developers or testing environments.
• Fewer compatibility issues: Dependencies are controlled by the package itself and/or the runtime, thus minimizing conflicts with system libraries.

Flatpak is also very attractive to developers. It allows you to publish the application directly without depending on a maintainer to package it for each distribution.Once you upload your app (for example, to Flathub), any Linux user with Flatpak enabled can install it with one or two commands. commandsor even from the graphics software store in your environment.

This immediacy means that A new version of your application can reach users of different distributions at the same time.This is especially interesting in distributions with slow release cycles where official packages take a long time to update. Furthermore, the runtime environment offers a homogeneous base, thus reducing the number of library combinations that need to be supported.

It's not all advantages. There are Some drawbacks and tolls to keep in mind:

• Package sizes: Flatpak packages typically take up more space than traditional native packages because they include additional dependencies or share large runtimes. This results in more downloads and increased disk usage.
• Slight performance penalty: Because it runs in a sandbox and has extra layers of abstraction, in some cases there may be a small impact on performance, although it is usually minimal for most users.
• Dependence on Flatpak repositories: If an app is only distributed via Flathub or another Flatpak repository, you are tied to that repo being kept alive and up-to-date.
• Packaging complexity: Creating a well-made Flatpak, especially for deployment on Flathub, can be much more laborious than it initially seems, particularly regarding dependencies and metadata.

Furthermore, when compared to other solutions like Snap, To be honest, the experience of packing and unpacking can be somewhat more confusing.The official instructions are somewhat scattered, and if your goal is to publish on Flathub, there are still more steps and requirements to meet.

How Flatpak works on a technical level

To fully understand how to create a Flatpak package, it's very helpful to have a clear understanding of its architecture. Flatpak is based on two fundamental pieces: runtimes and applicationsA runtime is a shared execution environment, such as org.gnome.Platform/x86_64/3.22, which provides a common base of libraries and components.

A Flatpak application declares in its metadata what runtime does it need to functionThis way, multiple apps can use the same runtime, saving space and ensuring compatibility. The result is something like, "the app relies on a stable and known platform, and everything that isn't on that platform is packaged within the app itself."

The applications run within isolated containers that restrict access to critical resourcesThis isolation is managed through configurable permissions: network access, file system directories, input devices, audio (PulseAudio), graphics server (X11/Wayland), D-Bus for inter-process communication, etc.

A key idea is that The departments are managed in a more predictable wayInstead of relying on system library versions, which can vary greatly between distributions and versions, the developer knows in advance what runtime will be available and, if something newer or more specific is needed, includes it directly in the package.

Distribution is usually done through repositories such as Flathub, which acts as a centralized repository for Flatpak applicationsFrom there, users can search for, download, and install apps with a single command or from the graphical store. It's also possible to create custom repositories, which is very useful in corporate or educational environments where applications are deployed in a controlled manner.

Prerequisites for creating a Flatpak package

Before you start packaging, you need to be clear about what Flatpak requires for everything to work. There are three basic requirements: having Flatpak installed, having a suitable runtime, and defining the package structure..

In virtually any modern distribution you can Install Flatpak from the distro's own package managerIn Arch Linux, for example, if you install GNOME with the package groups gnome y gnome-extraFlatpak is installed automatically as a dependency. If not, you can install it explicitly using your distro's package manager (pacman, apt, dnf, zypper, etc.).

The second step is configure at least one runtime environmentFor most desktop applications, it is common to rely on platforms such as org.gnome.Platform or those provided by KDE, always in the architecture and version you are going to use, for example x86_64/3.22.

Once you have Flatpak and the runtime ready, it's time to think about the package structure and in the fully qualified application nameFlatpak uses a convention of the type com.distribuidor.App o org.test.HelloThis is similar to reverse domain identifiers. This identifier will be used in all commands and in the manifest.

Finally, you will need the development tools corresponding to your language or technology, because Part of the process involves compiling or preparing the binaries that will then be put into the Flatpak containerIt's not the same to package a small shell script than a complex app in C++, Java, Python or Electron.

Basic structure of a Flatpak package

A Flatpak package is not just binaries. It includes several essential elements that describe the application and allow it to be integrated with the desktop.Typical components that make up a Flatpak package include:

• AppData (application metadata): Information files about the app (usually in XML format) that include description, screenshots, category, link to the official website, etc. These are essential for software stores to display the app correctly.
• Icons in various sizes: Images adapted to different screen densities, including high-resolution displays. They are installed in standard paths recognized by the desktop environment.
• .desktop files: Shortcuts that allow you to launch the application from the menu, the application launcher, or the dock of the desktop environment.
• D-Bus configuration and other services: Definitions for communication with the system message bus, as well as integration with PulseAudio for sound and X11/Wayland for graphical representation.
• Application-specific files: Executables, scripts, additional libraries, graphic resources, etc. In short, everything necessary for your program to work.

To better understand the structure, imagine you are creating a very simple example, a "Hello world" packaged with Flatpak. You could start by creating a directory hierarchy like this:

mkdir hello
mkdir hello/files
mkdir hello/files/bin
mkdir hello/export

In the folder hello/files/bin would you place the executable or script that you want to run, and in hello You would have the typical Flatpak metadata, such as the application file with the section [Application] where the name and launch order are specified.

A simplified example of metadata might look something like this, where The identifier, runtime, and main command to be executed are defined.:

[Application] name=org.test.Hello
runtime=org.gnome.Platform/x86_64/3.22
command=hello.sh

And the file hello.sh could be a simple shell script with this content, which would be installed within files/bin:

#!/bin/sh
echo "Hello world, from a sandbox"

This example is very basic, but This illustrates the idea that the Flatpak package contains, on the one hand, the application files and, on the other hand, all the information needed to integrate and run it correctly. within a specific execution environment.

General steps to create a Flatpak package step by step

Based on all of the above, we can summarize the basic flow for packaging an application in Flatpak. These steps are valid for both local tests and more serious publications. (although, as we will see, Flathub adds extra requirements):

1. Install Flatpak on your distribution If you don't already have it, use the native package manager (apt, dnf, pacman, etc.).
2. Configure a suitable runtimeFor example, by adding Flathub as a repository and downloading the runtime required for your app.
3. Define the package structure and its full identifier (of the kind com.tuempresa.TuApp), in addition to creating the file folders, metadata, icons, AppData, etc.
4. Build the package and export it to a repository local or remote, for example with a command like flatpak build-export repo helloWhere repo is the repository folder and hello It is the directory with the build.
5. Install the package from that repository and test it. to verify that everything works as expected within the sandbox.

The command flatpak build-export can be combined with GPG signatures for to guarantee the authenticity of the developer and the integrity of the packageThis is especially interesting when distributing applications in environments where cryptographic verification is important.

Note that The steps above describe a fairly straightforward, locally oriented workflowWhen we talk about Flathub, the story gets a little more complicated, because the repository does not accept pre-compiled packages, but rather compiles Flatpak files on its own servers with restricted network access.

Install, run, and manage Flatpak applications from the terminal

Once you have your package, or want to try others, Managing Flatpak applications from the command line is quite simpleLet's look at some typical examples that will help you understand how your own package would be used once it's packaged.

Imagine you have created a small repository called tutorial-repo that contains your sample application org.test.Hello. To add that repository and install the app only for your userYou could use:

flatpak --user remote-add --no-gpg-verify tutorial-repo repo
flatpak --user install tutorial-repo org.test.Hello
flatpak run org.test.Hello

Parameter --user indicates that the installation is performed in the user's personal directory, without requiring administrator permissions and without affecting the rest of the system accountsIt is ideal for multi-user environments where each person can decide which Flatpak applications they want to have.

A classic example is installing a game like GNOME Chess just for your user. The command might look like this (assuming you use Flathub as your repository):

flatpak install --user https://dl.flathub.org/repo/appstream/org.gnome.Chess.flatpakref

You can install applications by directly specifying the reference file .flatpakref, as with GIMP from Flathub, using something like:

flatpak install https://dl.flathub.org/repo/appstream/org.gimp.GIMP.flatpakref

To keep everything up to date, the command flatpak update It is responsible for updating installed applications.You can run it periodically or even integrate it into administration scripts, as is done in some educational or corporate environments where applications are deployed in system mode for all users.

In addition to installing and updating, Flatpak lets you List, uninstall, and clean applications and runtimes that you no longer use. The cleanup command is especially useful for deleting orphaned libraries and dependencies, freeing up disk space after uninstalling Flatpak applications.

Flathub, repositories and Flatpak application deployment

Flathub has established itself as the main and best-known repository of Flatpak applicationsIt is the place where most users look for new programs and where many developers publish updated versions of their desktop applications.

At Flathub you can find a huge variety of software, organized by categories such as audio and video, development, education, games, graphics, communication, productivity, science, utilities, etc.It includes well-known applications such as VLC, GIMP, LibreOffice, Audacity, SteamInkscape, Blender, Signal, Telegram, Calibre and many more.

From the Flathub website you can Find an application, click the INSTALL button and get the reference .flatpakref, which is then passed to the command flatpak installThis reference contains the information necessary for Flatpak to know from which remote to download the app, which runtime to use, etc.

If you are in a more controlled environment, such as a company or a school, It is also possible to create your own repositories and publish your applications in themIn many educational institutions, for example, Ansible or other automation tools are used to deploy Flatpak applications in system mode, so that they are available to all users of the computer.

System mode installation usually requires administrative privileges, but It offers the advantage that the apps are made available in a centralized manner.For its part, the installation with --user It is ideal for giving flexibility to each person without altering the machine's base software set.

Create a Flatpak package to publish it on Flathub

Here comes one of the most delicate parts. Building a working Flatpak on your machine is only half the storyIf you want to publish it on Flathub, the process has additional requirements and limitations that you should be aware of from the beginning to avoid getting frustrated.

To begin with, The instructions on the main Flatpak website focus on a fairly "open" build flow.In a traditional build environment, your build environment can access the network to download dependencies, clone repositories, and so on. However, Flathub compiles packages on its own servers, and the build process there doesn't have internet access. This means that everything you need must be described in the manifest with well-defined source URLs.

In other words, if your application depends on multiple external libraries or modules, You need to explicitly add the sources for each dependency in the Flatpak manifest.even if you already have one requirements.txt In the case of Python or another dependency file in your technology, this may force you to use (sometimes unpolished) helper scripts to generate these sections, and you'll still have to manually check things like build dependencies.

The practical consequence is that Resolving all dependencies and getting the offline build to work can take hoursThis is especially true in complex applications or those with many external libraries. In some high-level languages, such as Python, finding all the correct build dependencies can be quite tedious.

Another important point is that In Flathub you can't use just any runtime you want.You can only rely on the runtimes hosted on Flathub itself, which sometimes forces you to manually compile and include more dependencies than you'd like. This multiplies the packaging work and the amount of things you have to maintain long-term.

In addition to the manifesto and dependencies, Flathub demands a fairly detailed metadata fileThis includes information such as a detailed description, screenshots, links, licenses, categories, and, in many cases, release notes for each update. This requires ongoing maintenance every time you release a new version.

The deployment process is not trivial either. To publish to Flathub, you need to request a specific repository within the Flathub organization on GitHub.This involves going through a review process and configuring actions or workflows that integrate with Flathub's build infrastructure. The documentation mentions GitHub Actions, but doesn't always clearly explain how these actions fit with the organization's official repository.

For all these reasons, some developers, after testing, comment that Creating a Flatpak for Flathub can be frustrating and very time-consuming.This has led to the consideration of alternative formats like Snap when the goal is a more direct and less frictionless deployment. Even so, the advantage of reaching a very broad user base and multiple distributions makes the effort worthwhile in many cases.