Flatpak: Difference between revisions

Revision as of 19:45, 7 August 2025

Flatpak is a Linux application sandboxing and distribution framework.

This article extends the documentation in the NixOS manual.

Installation

Global

Using this configuration, flatpak will be installed and ready to use globally for all users:

❄︎ /etc/nixos/configuration.nix

services.flatpak.enable = true;

Per-User

If you'd rather make Flatpak available to a specific user, add flatpak to that user's packages. To be able to install Flatpaks graphically, add the gnome-software package. The result will look something like this:

❄︎ /etc/nixos/configuration.nix

users.users."user" = {
    packages = with pkgs; [
      flatpak
      gnome-software
    ];
  };

Window Managers / Compositors Patches

After adding the desired solution to your configuration file, Flatpak will be installed, but it is not always added to your path directly, e.g. when you are using Sway.

To manually add it to the path while using the Greetd login manager and Sway, create a .profile file with an override for your XDG_DATA_DIRS path, e.g.:

≡︎ .profile

export XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share:/var/lib/flatpak/exports/share:$HOME/.local/share/flatpak/exports/share

This is also required when installing flatpak on a per-user basis.

Usage

Declarative

To manage Flatpak declaratively, you can either use nix-flatpak or declarative-flatpak

In the event of a Nix rollback, both modules will reinstall the previously declared Flatpak packages

nix-flatpak

A convergent approach to Flatpak management where refs are managed in place

Flatpak packages are not cached in the Nix store

It supports flakes or home-manager, but doesn't support non-flakes only

declarative-flatpak

A congruent approach to Flatpak management where changes are designed to be atomic, ensuring that either they succeed or nothing happens. This module uses a temporary installation and then overwrites the current one.

It supports non-flake, flakes, and home-manager

For more details, see declarative-flatpak/issues/44

Imperative

To manage Flatpak imperatively, you can use the flatpak CLI (flatpak CLI Reference Documentation)

Example

$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
$ flatpak update
$ flatpak search Flatseal
$ flatpak install flathub com.github.tchx84.Flatseal
$ flatpak run com.github.tchx84.Flatseal

Configure Repositories Globally

To automatically configure Flatpak repositories for all users, this needs to be added to configuration.nix:

❄︎ /etc/nixos/configuration.nix

systemd.services.flatpak-repo = {
    wantedBy = [ "multi-user.target" ];
    path = [ pkgs.flatpak ];
    script = ''
      flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
    '';
  };

Development

Build a Flatpak project

The following example builds a demo app of the libadwaita repository using flatpak-builder, installs it locally in the user space and runs it. First install flatpak and flatpak-builder on your system

❄︎ /etc/nixos/configuration.nix

services.flatpak.enable = true;
environment.systemPackages = [
  pkgs.flatpak-builder
];

Clone, build and run the example project.

$ flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
$ flatpak install gnome-nightly org.gnome.Sdk org.gnome.Platform
$ git clone https://gitlab.gnome.org/GNOME/libadwaita.git
$ cd libadwaita
$ nix shell nixpkgs#appstream
$ flatpak-builder --disable-tests --user --install build demo/org.gnome.Adwaita1.Demo.json
$ flatpak run org.gnome.Adwaita1.Demo.json

Note that the gnome-nightly repository and the appstream dependency are especially required for this specific project and might be different for other Flatpak projects.

Tips and tricks

Emulate Flatpaks of different architecture

It is possible to install and run Flatpaks which were compiled for a different platform.

In this example we imperatively install the application "Metronome" aarch64 Flatpak package and run it (regardless of the architecture of the host, but in that case, it was x86_64):

$ flatpak install flathub com.adrienplazas.Metronome --arch=aarch64
$ flatpak run com.adrienplazas.Metronome

To support emulation with Qemu, following Binfmt configuration is required.

Troubleshooting

Missing themes and cursors

If you have issues with cursors or themes in general, take a look at Fonts#Flatpak_applications_can't_find_system_fonts

@@ Line 3: / Line 3: @@
 This article extends the documentation in the [https://nixos.org/manual/nixos/stable/#module-services-flatpak NixOS manual].
-== Usage ==
+== Installation ==
+=== Global ===
 Using this configuration, <code>flatpak</code> will be installed and ready to use globally for all users:
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+{{file|3=services.flatpak.enable = true;|name=/etc/nixos/configuration.nix|lang=nix}}
-services.flatpak.enable = true;
+=== Per-User ===
-</nowiki>}}
 If you'd rather make Flatpak available to a specific user, add <code>flatpak</code> to that user's packages. To be able to install Flatpaks graphically, add the <code>gnome-software</code> package. The result will look something like this:
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+{{file|3=users.users."user" = {
-  users.users."user" = {
      packages = with pkgs; [
        flatpak
        gnome-software
      ];
-   };
+   };|name=/etc/nixos/configuration.nix|lang=nix}}
-</nowiki>}}
+=== Window Managers / Compositors Patches ===
 After adding the desired solution to your configuration file, Flatpak will be installed, but it is not always added to your path directly, e.g. when you are using Sway.
 To manually add it to the path while using the [[Greetd]] login manager and [[Sway]], create a <code>.profile</code> file with an override for your <code>XDG_DATA_DIRS</code> path, e.g.:
-{{file|.profile|nix|<nowiki>
+{{file|3=export XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share:/var/lib/flatpak/exports/share:$HOME/.local/share/flatpak/exports/share|name=.profile|lang=}}
-export XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share:/var/lib/flatpak/exports/share:$HOME/.local/share/flatpak/exports/share
-</nowiki>}}
 This is also required when installing <code>flatpak</code> on a per-user basis.
-To start using flatpaks, particularly for flatpak development:
+== Usage ==
+=== Declarative ===
+To manage Flatpak declaratively, you can either use [https://github.com/gmodena/nix-flatpak nix-flatpak] or [https://github.com/in-a-dil-emma/declarative-flatpak declarative-flatpak]
+In the event of a Nix rollback, both modules will reinstall the previously declared Flatpak packages
+==== [https://github.com/gmodena/nix-flatpak nix-flatpak] ====
+A convergent approach to Flatpak management where refs are managed in place
+Flatpak packages are not cached in the Nix store
+It supports flakes or [https://github.com/nix-community/home-manager home-manager], but doesn't support non-flakes only
+==== [https://github.com/in-a-dil-emma/declarative-flatpak declarative-flatpak] ====
+A congruent approach to Flatpak management where changes are designed to be atomic, ensuring that either they succeed or nothing happens. This module uses a temporary installation and then overwrites the current one.
+It supports non-flake, flakes, and [https://github.com/nix-community/home-manager home-manager]
-<syntaxHighlight lang=console>
+<small>For more details, see [https://github.com/in-a-dil-emma/declarative-flatpak/issues/44 declarative-flatpak/issues/44]</small>
-$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+=== Imperative ===
+To manage Flatpak imperatively, you can use [https://docs.flatpak.org/en/latest/using-flatpak.html the <code>flatpak</code> CLI] ([https://docs.flatpak.org/en/latest/flatpak-command-reference.html <code>flatpak</code> CLI Reference Documentation])
+==== Example ====
+<syntaxhighlight lang="console">$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
 $ flatpak update
-$ flatpak search bustle
+$ flatpak search Flatseal
-$ flatpak install flathub org.freedesktop.Bustle
+$ flatpak install flathub com.github.tchx84.Flatseal
-$ flatpak run org.freedesktop.Bustle
+$ flatpak run com.github.tchx84.Flatseal</syntaxhighlight>
-</syntaxHighlight>
-To automatically configure a flatpak repository for all users using the global configuration file, add this to your configuration.nix file.
+==== Configure Repositories Globally ====
+To automatically configure Flatpak repositories for all users, this needs to be added to <code>configuration.nix</code>:{{file|3=systemd.services.flatpak-repo = {
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
-  systemd.services.flatpak-repo = {
      wantedBy = [ "multi-user.target" ];
      path = [ pkgs.flatpak ];
@@ Line 48: / Line 63: @@
        flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
      '';
-   };
+   };|name=/etc/nixos/configuration.nix|lang=nix}}
-</nowiki>}}
 == Development ==
@@ Line 57: / Line 71: @@
 The following example builds a demo app of the [https://github.com/GNOME/libadwaita libadwaita] repository using <code>flatpak-builder</code>, installs it locally in the user space and runs it. First install <code>flatpak</code> and <code>flatpak-builder</code> on your system
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+{{file|3=services.flatpak.enable = true;
-services.flatpak.enable = true;
+environment.systemPackages = [
-environment.systemPackages = [ pkgs.flatpak-builder ];
+  pkgs.flatpak-builder
-</nowiki>}}
+];|name=/etc/nixos/configuration.nix|lang=nix}}
 Clone, build and run the example project.
-<syntaxhighlight lang="console">
+<syntaxhighlight lang="console">$ flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
-$ flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
 $ flatpak install gnome-nightly org.gnome.Sdk org.gnome.Platform
 $ git clone https://gitlab.gnome.org/GNOME/libadwaita.git
@@ Line 71: / Line 84: @@
 $ nix shell nixpkgs#appstream
 $ flatpak-builder --disable-tests --user --install build demo/org.gnome.Adwaita1.Demo.json
-$ flatpak run org.gnome.Adwaita1.Demo.json
+$ flatpak run org.gnome.Adwaita1.Demo.json</syntaxhighlight>
-</syntaxhighlight>
 Note that the <code>gnome-nightly</code> repository and the <code>appstream</code> dependency are especially required for this specific project and might be different for other Flatpak projects.
@@ Line 79: / Line 91: @@
 === Emulate Flatpaks of different architecture ===
-It is possible to install and run Flatpaks which were compiled for a different platform. In this example we start the application ''Metronome'' as aarch64 Flatpak on a x86_64 host:<syntaxhighlight lang="bash">
+It is possible to install and run Flatpaks which were compiled for a different platform.
-flatpak install --user --arch=aarch64 flathub com.adrienplazas.Metronome
-flatpak run --user com.adrienplazas.Metronome
+In this example we imperatively install the application "Metronome" <code>aarch64</code> Flatpak package and run it (regardless of the architecture of the host, but in that case, it was <code>x86_64</code>):<syntaxhighlight lang="console">$ flatpak install flathub com.adrienplazas.Metronome --arch=aarch64
-</syntaxhighlight>To support emulation with Qemu, [[QEMU#Run binaries of different architecture|following Binfmt configuration]] is required.
+$ flatpak run com.adrienplazas.Metronome</syntaxhighlight>To support emulation with Qemu, [[QEMU#Run binaries of different architecture|following Binfmt configuration]] is required.
 == Troubleshooting ==