Flatpak: Difference between revisions

Latest revision as of 19:58, 1 February 2025

Flatpak is a Linux application sandboxing and distribution framework.

This article extends the documentation in the NixOS manual.

Usage

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

/etc/nixos/configuration.nix

services.flatpak.enable = true;

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
    ];
  };

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.

To start using flatpaks, particularly for flatpak development:

$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
$ flatpak update
$ flatpak search bustle
$ flatpak install flathub org.freedesktop.Bustle
$ flatpak run org.freedesktop.Bustle

To automatically configure a flatpak repository for all users using the global configuration file, add this to your configuration.nix file.

/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 start the application Metronome as aarch64 Flatpak on a x86_64 host:

flatpak install --user --arch=aarch64 flathub com.adrienplazas.Metronome
flatpak run --user 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 1: / Line 1: @@
-[https://www.flatpak.org/ Flatpak] is a linux application sandboxing and distribution framework
+[https://www.flatpak.org/ Flatpak] is a Linux application sandboxing and distribution framework.
+This article extends the documentation in the [https://nixos.org/manual/nixos/stable/#module-services-flatpak NixOS manual].
 == Usage ==
-Using this configuration, <code>flatpak</code> will be installed and ready for use globally for all users:
+Using this configuration, <code>flatpak</code> will be installed and ready to use globally for all users:
 {{file|/etc/nixos/configuration.nix|nix|<nowiki>
 services.flatpak.enable = true;
 </nowiki>}}
-If you'd rather make flatpak available on a specific user rather than globally, add <code>flatpak</code> to that user's packages. To be able to install flatpaks graphically, add the <code>gnome.gnome-software</code> package. The result will look something like this:
+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>
-   users.users.myflatpakuser = {
+   users.users."user" = {
      packages = with pkgs; [
        flatpak
-       gnome.gnome-software
+       gnome-software
      ];
    };
 </nowiki>}}
-After adding the desired solution to your configuration file, flatpak will be installed, however it is not always added to your path directly, e.g. when you are using sway it will be not.
+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 path while using a [https://nixos.wiki/wiki/Greetd greetd] login manager and [https://nixos.wiki/wiki/Sway Sway] create a <code>.profile</code> file with an override for your <code>XDG_DATA_DIRS</code> path, e.g.:
+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>
 export XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share:/var/lib/flatpak/exports/share:$HOME/.local/share/flatpak/exports/share
@@ Line 29: / Line 31: @@
 To start using flatpaks, particularly for flatpak development:
-<syntaxHighlight>
+<syntaxHighlight lang=console>
-flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
+$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
-flatpak update
+$ flatpak update
-flatpak search bustle
+$ flatpak search bustle
-flatpak install flathub org.freedesktop.Bustle
+$ flatpak install flathub org.freedesktop.Bustle
-flatpak run org.freedesktop.Bustle
+$ flatpak run org.freedesktop.Bustle
 </syntaxHighlight>
+To automatically configure a flatpak repository for all users using the global configuration file, add this to your configuration.nix file.
+{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+  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
+    '';
+  };
+</nowiki>}}
 == Development ==
-=== Build Flatpak project ===
+=== Build a Flatpak project ===
-The following example builds a demo project of the [https://gitlab.gnome.org/GNOME/libhandy libhandy] repository using <code>flatpak-builder</code>, installs it locally in the user space and run it. First install <code>flatpak</code> and <code>flatpak-builder</code> on your system
+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>
@@ Line 48: / Line 62: @@
 </nowiki>}}
-Clone, build and run the example project
+Clone, build and run the example project.
-<syntaxHighlight>
+<syntaxhighlight lang="console">
-flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatp
+$ flatpak remote-add --if-not-exists gnome-nightly https://nightly.gnome.org/gnome-nightly.flatpakrepo
-akrepo
+$ flatpak install gnome-nightly org.gnome.Sdk org.gnome.Platform
-flatpak install org.gnome.Sdk/x86_64/master org.gnome.Platform/x86_64/master
+$ git clone https://gitlab.gnome.org/GNOME/libadwaita.git
-git clone https://gitlab.gnome.org/GNOME/libhandy.git
+$ cd libadwaita
-cd libhandy
+$ nix shell nixpkgs#appstream
-flatpak-builder --user --install _flatpak examples/sm.puri.Handy.Demo.json
+$ flatpak-builder --disable-tests --user --install build demo/org.gnome.Adwaita1.Demo.json
-flatpak run sm.puri.Handy.Demo
+$ 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.
+== 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 start the application ''Metronome'' as aarch64 Flatpak on a x86_64 host:<syntaxhighlight lang="bash">
+flatpak install --user --arch=aarch64 flathub com.adrienplazas.Metronome
+flatpak run --user com.adrienplazas.Metronome
+</syntaxhighlight>To support emulation with Qemu, [[QEMU#Run binaries of different architecture|following Binfmt configuration]] is required.
 == Troubleshooting ==
@@ Line 64: / Line 88: @@
 === Missing themes and cursors ===
-If you have issues with cursors or themes in general, take a look at [https://nixos.wiki/wiki/Fonts#Flatpak_applications_can.27t_find_system_fonts Fonts]
+If you have issues with cursors or themes in general, take a look at [[Fonts#Flatpak_applications_can't_find_system_fonts]]
+[[Category:Software]]
+[[Category:NixOS Manual]]