Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Install Flatpak

In this chapter, you will install Flatpak and prepare the required runtime environment for building and running the application inside a sandbox.

Flatpak is an essential part of modern Linux application distribution.

What Is Flatpak?

Flatpak is a system for:

  • Building applications
  • Distributing applications
  • Running applications in a sandbox

Unlike traditional package managers, Flatpak:

  • Bundles application dependencies
  • Runs looking at a defined runtime
  • Is isolated from the host system
  • Works across different Linux distributions

Flatpak ensures that your application runs consistently across systems.

Why We Use Flatpak in This Tutorial

In modern GNOME and LinuxMobile development:

  • Applications are expected to be sandboxed
  • Distribution often happens through Flathub
  • Runtimes are standardized (e.g., GNOME Platform)

Using Flatpak allows you to:

  • Reproduce builds reliably
  • Avoid host system conflicts
  • Test your application in a controlled environment

Step 1 - Install Flatpak

Run:

sudo apt install flatpak -y

Now verify installation:

flatpak --version

Step 2 - Add Flathub Repository

Flathub is the main Flatpak application repository.

Add it with:

flatpak remote-add --if-not-exists flathub \
https://flathub.org/repo/flathub.flatpakrepo

This allows your system to download runtimes and SDKs.

Step 3 - Install GNOME Runtime

Our project uses:

  • GNOME Platform
  • GNOME SDK
  • Version 49

Install the runtime:

flatpak install flathub org.gnome.Platform//49

Install the SDK:

flatpak install flathub org.gnome.Sdk//49

The runtime provides:

  • GTK libraries
  • System dependencies
  • Shared components

The SDK provides:

  • Development tools
  • Build utilities
  • Compilation support

Step 4 - Install Rust SDK Extension

Since we are building a Rust application, we must install the Rust extension for the GNOME SDK.

Run:

flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable

After running this command, Flatpak will show a list of available versions.

It will look similar to this:

Looking for matches...

1) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/21.08
2) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/1.6
3) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/22.08
4) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/23.08
5) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/18.08
6) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/24.08
7) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/19.08
8) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/25.08
9) runtime/org.freedesktop.Sdk.Extension.rust-stable/x86_64/20.08

Flatpak will then ask:

Which do you want to use (0 to abort)? [0-9]:

What should you type?

Type:

8

and press Enter.

The number 8 selects the latest stable Rust SDK version (25.08). Using the newest version ensures compatibility with the latest GNOME SDK and Rust tooling.

After selecting the number, Flatpak will start downloading the Rust toolchain.

You will see something like:

Installing...
22% 1.5 MB/s

Wait until the installation finishes.

This extension provides:

  • Rust compiler inside the Flatpak build environment
  • Cargo support
  • Required toolchain integration

Without this extension, Flatpak builds will fail.

Step 5 - Verify Installed Runtimes

List installed runtimes:

flatpak list

You should see entries for:

  • org.gnome.Platform 49
  • org.gnome.Sdk 49
  • org.freedesktop.Sdk.Extension.rust-stable

If they appear, your Flatpak environment is ready.

Understanding Runtime vs SDK

Runtime

The runtime is what your application runs on.

It contains:

  • GTK
  • System libraries
  • Shared components

It ensures consistency across different Linux systems.

SDK

The SDK is used during build time.

It contains:

  • Compilers
  • Debug tools
  • Headers
  • Build environment tools

You build against the SDK. Users run against the runtime.

Why Flatpak Matters for Onboarding

Flatpak introduces additional complexity:

  • Large runtime downloads
  • Version alignment requirements
  • Sandbox permissions
  • Manifest configuration

Understanding these early helps you:

  • Debug build errors
  • Understand permission requirements
  • Package applications correctly

Flatpak is not just a packaging tool it defines the application environment.

Common Issues and Solutions

Runtime Version Not Found

If you see:

Requested runtime not installed

Make sure you specify the correct version:

org.gnome.Platform//49

Check available versions:

flatpak search org.gnome.Platform

Rust Extension Version Mismatch

If you see:

Requested extension not installed

Install the rust-stable extension without specifying version:

flatpak install flathub org.freedesktop.Sdk.Extension.rust-stable

Disk Space Issues

Flatpak runtimes can consume several gigabytes.

If space is limited:

flatpak uninstall --unused

for more details go through the Flatpak Documentation