Flatpak
Flatpak is a Linux application sandboxing and distribution framework.
This article extends the documentation in the NixOS manual.
Flatpak on NixOS can be used either in a declarative or imperative way. The imperative way is better suited for beginners, If you're just starting out with NixOS, and/or don't want to deal with advanced configuration, refer to the Imperative installation section.
Declarative installation
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
A convergent approach to Flatpak management where refs are managed in place. It supports flakes or home-manager, but doesn't support installation without flakes. Flatpak packages are not cached in the Nix store.
Installation
Add nix-flatpak to your flake inputs and import the module. Below is an example flake.nix
{
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=latest";
};
outputs = { self, nixpkgs, nix-flatpak, ... } @ inputs:
{
nixosConfigurations.YOURHOSTNAME = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs; };
modules = [
nix-flatpak.nixosModules.nix-flatpak
];
};
};
}
After adding nix-flatpak to your flake inputs and importing the module, packages can be installed declaratively;
services.flatpak.enable = true;
services.flatpak.packages = [
{ appId = "com.brave.Browser"; origin = "flathub"; }
"com.obsproject.Studio"
];
Managing remotes
nix-flatpak will add the flathub remote by default. You may also declare your own additional remotes. Doing so will override the default configuration, so you will need to also declare flathub as a remote if you wish to use it.
services.flatpak.remotes = [
{
name = "flathub-beta";
location = "https://flathub.org/beta-repo/flathub-beta.flatpakrepo";
}
{
name = "flathub";
location = "https://dl.flathub.org/repo/flathub.flatpakrepo";
}
];
Installing a .flatpak file declaratively
Add the file you want to install as a flake input. Orca slicer nightly will be used as an example:
inputs = {
nixpkgs.url = "github:nixos/nixpkgs?ref=nixos-unstable";
nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=latest";
orca-slicer = {
url = "https://github.com/OrcaSlicer/OrcaSlicer/releases/download/nightly-builds/OrcaSlicer-Linux-flatpak_nightly_x86_64.flatpak";
flake = false;
};
};
In your configuration.nix, add the .flatpak file from your inputs to your packages:
{config, pkgs, lib, inputs, ... }:
{
services.flatpak.packages = [
{
appId = "com.orcaslicer.OrcaSlicer";
bundle = inputs.orca-slicer.outPath;
sha256 = inputs.orca-slicer.narHash;
}
];
}
Managing permissions
Instead of using software like Flatseal or using flatpak override one can also manage flatpak permissions in a declarative manner. Below is an example forcing the Adwaita dark theme globally and enabling GPU acceleration for orca slicer.
services.flatpak.overrides.settings = {
global = {
Environment.GTK_THEME = "Adwaita:dark";
};
"com.orcaslicer.OrcaSlicer " = {
Context.devices = ["dri"];
};
};
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
Imperative installation
Global
Using this configuration, flatpak will be installed and ready to use globally for all users.
services.flatpak.enable = true;
Per-User
If you'd rather make Flatpak available to a specific user, add flatpak to that user's packages
users.users."user" = {
packages = with pkgs; [
flatpak
];
};
Terminal User Interface
To manage Flatpak imperatively, you can use the flatpak command (flatpak Command 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
Graphical User Interface
To install Flatpaks graphically, you can use the GNOME Software Application (gnome-software in nixpkgs)
Configure Repositories Globally
Otherwise, the following section could conflict with them
If you are, prefer using nix-flatpak'sservices.flatpak.remotes or declarative-flatpak's services.flatpak.remotes instead
To automatically configure Flatpak repositories for all users, one can add this snippet to 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
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.
Using Flatpak with Impermanence
If you're using Impermanence, you'll need to make sure you persist the directories that flatpak will be using
/var/lib/flatpak(for system configuration, repositories, etc.)~/.var/app(for app data)~/.local/share/flatpak(for user-specific configuration)
The directories in your home (starting with ~) will need to be persisted for every user who will use flatpak
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
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.:
export XDG_DATA_DIRS=$XDG_DATA_DIRS:/usr/share:/var/lib/flatpak/exports/share:$HOME/.local/share/flatpak/exports/shareThis is also required when installing flatpak on a per-user basis.
Uninstalling an application and wiping its data
Sometimes, flatpak applications may glitch (like fonts in Flatseal[1]) 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 --delete-data flag when uninstalling the offending application, (like flatpak uninstall <application> --delete-data ). Then re-install the offending application (like flatpak install <application> ).
Option 2: Delete application and then delete its data
This is useful if you have set up flatpak declaratively[2]. First remove the application from your configuration and rebuild. Then run flatpak uninstall --unused --delete-data 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.