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

nix-flatpak

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

❄︎ 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;

❄︎ configuration.nix

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.

❄︎ configuration.nix

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:

❄︎ flake.nix

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:

❄︎ /etc/nixos/configuration.nix

{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.

❄︎ /etc/nixos/configuration.nix

services.flatpak.overrides.settings = {
  global = {
    Environment.GTK_THEME = "Adwaita:dark";
  };
  "com.orcaslicer.OrcaSlicer " = {
      Context.devices = ["dri"];
  };
};

declarative-flatpak

☶︎

This section needs to be expanded. Examples are missing Further information may be found in the related discussion page. Please consult the pedia article metapage for guidelines on contributing.

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.

❄︎ /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

❄︎ /etc/nixos/configuration.nix

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

⚠︎

Warning: This assumes you are not installing Flatpak packages declaratively (using nix-flatpak or declarative-flatpak)

Otherwise, the following section could conflict with them

If you are, prefer using nix-flatpak's services.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:

❄︎ /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.

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

≡︎ .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.

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) 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. 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.