Getting started with flatpak

A Practical Guide to Sandboxed Apps on Linux

guide

Flatpak is a universal packaging system that lets developers ship applications in a sandboxed environment, independent of the host distribution’s libraries. This guide walks you through installing and configuring Flatpak on the most common Linux distributions, adding the primary Flatpak repository (Flathub), managing applications, handling permissions, and troubleshooting common problems—all in a technical yet approachable style.

Prerequisites

  • A recent Linux kernel (most modern distros meet this automatically).
  • A working internet connection for downloading packages and repositories.
  • Administrative privileges (sudo) for system‑wide installation.

Installation by Distribution

Distribution Package Manager Install Command Notes
Debian/Ubuntu (and derivatives) apt sudo apt update && sudo apt install flatpak For Ubuntu 20.04+ the package is in the default repos.
Fedora dnf sudo dnf install flatpak Fedora includes Flatpak in the default repos.
CentOS/RHEL 8+ dnf sudo dnf install flatpak Requires enabling the AppStream repo.
Arch Linux pacman sudo pacman -S flatpak Arch’s community repo.
openSUSE Tumbleweed zypper sudo zypper install flatpak Tumbleweed includes Flatpak.
openSUSE Leap zypper sudo zypper install flatpak Leap 15.4+ includes Flatpak.
Gentoo emerge sudo emerge --ask app-misc/flatpak Use the ~amd64 or ~x86_64 profile.

Post‑Installation Setup

  1. Add the Flathub repository (the primary source of Flatpak apps):

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

    Flathub hosts thousands of applications and is the recommended source.

  2. Enable the Flatpak runtime (if not automatically installed):

    flatpak install flathub org.freedesktop.Platform//23.08

    Replace 23.08 with the latest platform version.

  3. Configure system integration (optional but recommended):

    • GNOME: sudo apt install gnome-software-plugin-flatpak (Debian/Ubuntu) or sudo dnf install gnome-software-plugin-flatpak (Fedora).
    • KDE: sudo apt install plasma-discover-flatpak (Debian/Ubuntu) or sudo dnf install plasma-discover-flatpak (Fedora).

Using Flatpak

  • Install an application: flatpak install flathub org.gimp.GIMP
  • Run an application: flatpak run org.gimp.GIMP
  • List installed applications: flatpak list
  • Update all applications: flatpak update
  • Remove an application: flatpak uninstall org.gimp.GIMP

Managing Permissions and Sandboxing

Flatpak uses AppArmor or SELinux profiles to sandbox applications. Permissions can be granted via the flatpak override command:

flatpak override --user --filesystem=home org.gimp.GIMP

This example gives GIMP read/write access to the user’s home directory. For more granular control, consult the Flatpak documentation on “Permissions” and “Sandboxing”.

Troubleshooting Common Issues

Symptom Likely Cause Fix
flatpak: command not found Flatpak not installed or PATH not updated Re‑install or add /usr/bin to PATH
Application fails to launch Missing runtime or incompatible architecture Install the required runtime (flatpak install flathub org.freedesktop.Platform//...)
Network errors during install Proxy or firewall blocking HTTPS Configure proxy settings in /etc/flatpak/flatpak.conf or use --proxy flag
Permissions denied App sandbox restrictions Use flatpak override to grant needed access

Advanced Topics

  • Flatpak Remotes: Add additional remotes beyond Flathub, e.g., flatpak remote-add --if-not-exists myrepo https://example.com/repo.flatpakrepo.
  • Flatpak Snapshots: Use flatpak snapshot to create a backup of an app’s current state.
  • Flatpak System vs User Install: By default, flatpak install installs for the current user. Use --system to install system‑wide (requires root).

Resources for Further Reading

These steps provide a comprehensive workflow for installing, configuring, and managing Flatpak on most Linux systems, ensuring you can take advantage of sandboxed, distribution‑agnostic applications.