Flatpak: Difference between revisions

(21 intermediate revisions by 4 users not shown)

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

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~~:

=== With Impermanence ===

If you're using [[Impermanence]], you'll need to make sure you persist the directories that flatpak will be using

* <code>/var/lib/flatpak</code> (for system configuration, repositories, etc.)

* <code>~/.var/app</code> (for app data)

* <code>~/.local/share/flatpak</code> (for user-specific configuration)

The directories in your home (starting with <code>~</code>) will need to be persisted for every user who will use flatpak

== 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 [[Home Manager|home-manager]], but doesn't support non-flakes only

For more details, see [https://github.com/gmodena/nix-flatpak/discussions/168 nix-flatpak/discussions/168]

==== [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 [[Home Manager|home-manager]]

For more details, see [https://github.com/in-a-dil-emma/declarative-flatpak/issues/44 declarative-flatpak/issues/44]

<~~syntaxHighlight~~ lang=console>

=== Imperative ===

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

==== Terminal User Interface ====

To manage Flatpak imperatively, you can use [https://docs.flatpak.org/en/latest/using-flatpak.html the <code>flatpak</code> command] ([https://docs.flatpak.org/en/latest/flatpak-command-reference.html <code>flatpak</code> Command 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~~.

==== Graphical User Interface ====

To install Flatpaks graphically, you can use [https://apps.gnome.org/en-GB/Software/ the GNOME Software Application] ([https://search.nixos.org/packages?show=gnome-software <code>gnome-software</code> in nixpkgs])

{{~~file~~|/~~etc~~/nixos/~~configuration~~.nix|nix|<~~nowiki~~>

'''Note''': installing Flatpaks through it is imperative

systemd.services.flatpak-repo = {

==== Configure Repositories Globally ====

{{Warning|This assumes you are not installing Flatpak packages [https://wiki.nixos.org/wiki/Flatpak#Declarative declaratively] (using [https://wiki.nixos.org/wiki/Flatpak#nix-flatpak nix-flatpak] or [https://wiki.nixos.org/wiki/Flatpak#declarative-flatpak declarative-flatpak])

Otherwise, the following section could conflict with them

If you are, prefer using [https://wiki.nixos.org/wiki/Flatpak#nix-flatpak nix-flatpak]'s <code>services.flatpak.remotes</code> or [https://wiki.nixos.org/wiki/Flatpak#declarative-flatpak declarative-flatpak]'s <code>services.flatpak.remotes</code> instead}}

To automatically configure Flatpak repositories for all users, one can add this snippet to <code>configuration.nix</code>:{{file|3=systemd.services.flatpak-repo = {

wantedBy = [ "multi-user.target" ];

path = [ pkgs.flatpak ];

Line 48:

Line 87:

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 95:

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">$ 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 108:

$ 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 115:

=== 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 ==

Line 89:

Line 125:

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

=== Uninstalling an application and wiping its data ===

{{Warning|This involves deleting application data of flatpak applications, make sure to keep backed up any flatpak application data you want before proceeding.}}

Sometimes, flatpak applications may glitch (like fonts in Flatseal<ref>https://github.com/tchx84/Flatseal/issues/501</ref>) and wiping their data may solve the issue. To do so, you have two options.

==== Option 1: Delete application and its data in a single command ====

This is useful if you have installed the flatpak application '''imperatively'''. Use the <code>--delete-data</code> flag when uninstalling the offending application, (like <code>flatpak uninstall <application> --delete-data</code> ). Then re-install the offending application (like <code>flatpak install <application></code> ).

==== Option 2: Delete application and then delete its data ====

This is useful if you have set up flatpak '''declaratively'''<ref>[[Flatpak#Declarative]]</ref>. First remove the application from your configuration and rebuild. Then run <code>flatpak uninstall --unused --delete-data</code> to both delete '''all''' leftover applications and wipe the data of anything previously deleted. This will ask you to delete the data of each application individually, delete only the data of the offending application. Then re-add the offending application in your configuration and rebuild.

[[Category:Software]]

[[Category:NixOS Manual]]

@@ 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
-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:
+=== With Impermanence ===
+If you're using [[Impermanence]], you'll need to make sure you persist the directories that flatpak will be using
+* <code>/var/lib/flatpak</code> (for system configuration, repositories, etc.)
+* <code>~/.var/app</code> (for app data)
+* <code>~/.local/share/flatpak</code> (for user-specific configuration)
+The directories in your home (starting with <code>~</code>) will need to be persisted for every user who will use flatpak
+== 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
+{{Expand|reason=Examples are missing|scope=section}}
+==== [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 [[Home Manager|home-manager]], but doesn't support non-flakes only
+<small>For more details, see [https://github.com/gmodena/nix-flatpak/discussions/168 nix-flatpak/discussions/168]</small>
+==== [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 [[Home Manager|home-manager]]
+<small>For more details, see [https://github.com/in-a-dil-emma/declarative-flatpak/issues/44 declarative-flatpak/issues/44]</small>
-<syntaxHighlight lang=console>
+=== Imperative ===
-$ flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+==== Terminal User Interface ====
+To manage Flatpak imperatively, you can use [https://docs.flatpak.org/en/latest/using-flatpak.html the <code>flatpak</code> command] ([https://docs.flatpak.org/en/latest/flatpak-command-reference.html <code>flatpak</code> Command 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.
+==== Graphical User Interface ====
+To install Flatpaks graphically, you can use [https://apps.gnome.org/en-GB/Software/ the GNOME Software Application] ([https://search.nixos.org/packages?show=gnome-software <code>gnome-software</code> in nixpkgs])
-{{file|/etc/nixos/configuration.nix|nix|<nowiki>
+<small>'''Note''': installing Flatpaks through it is imperative</small>
-  systemd.services.flatpak-repo = {
+==== Configure Repositories Globally ====
+{{Warning|This assumes you are not installing Flatpak packages [https://wiki.nixos.org/wiki/Flatpak#Declarative declaratively] (using [https://wiki.nixos.org/wiki/Flatpak#nix-flatpak nix-flatpak] or [https://wiki.nixos.org/wiki/Flatpak#declarative-flatpak declarative-flatpak])
+Otherwise, the following section could conflict with them
+If you are, prefer using [https://wiki.nixos.org/wiki/Flatpak#nix-flatpak nix-flatpak]'s <code>services.flatpak.remotes</code> or [https://wiki.nixos.org/wiki/Flatpak#declarative-flatpak declarative-flatpak]'s <code>services.flatpak.remotes</code> instead}}
+To automatically configure Flatpak repositories for all users, one can add this snippet to <code>configuration.nix</code>:{{file|3=systemd.services.flatpak-repo = {
      wantedBy = [ "multi-user.target" ];
      path = [ pkgs.flatpak ];
@@ Line 48: / Line 87: @@
        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 95: @@
 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 108: @@
 $ 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 115: @@
 === 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 ==
@@ Line 89: / Line 125: @@
 If you have issues with cursors or themes in general, take a look at [[Fonts#Flatpak_applications_can't_find_system_fonts]]
+=== Uninstalling an application and wiping its data ===
+{{Warning|This involves deleting application data of flatpak applications, make sure to keep backed up any flatpak application data you want before proceeding.}}
+Sometimes, flatpak applications may glitch (like fonts in Flatseal<ref>https://github.com/tchx84/Flatseal/issues/501</ref>) and wiping their data may solve the issue. To do so, you have two options.
+==== Option 1: Delete application and its data in a single command ====
+This is useful if you have installed the flatpak application '''imperatively'''. Use the <code>--delete-data</code> flag when uninstalling the offending application, (like <code>flatpak uninstall <application> --delete-data</code> ). Then re-install the offending application (like <code>flatpak install <application></code> ).
+==== Option 2: Delete application and then delete its data ====
+This is useful if you have set up flatpak '''declaratively'''<ref>[[Flatpak#Declarative]]</ref>. First remove the application from your configuration and rebuild. Then run <code>flatpak uninstall --unused --delete-data</code> to both delete '''all''' leftover applications and wipe the data of anything previously deleted. This will ask you to delete the data of each application individually, delete only the data of the offending application. Then re-add the offending application in your configuration and rebuild.
 [[Category:Software]]
 [[Category:NixOS Manual]]