Declarative flatpaks

Declaratively manage Flatpak installations in NixOS and your $HOME

Important

The setup script performs changes in a transaction. Errors cause the transaction to fail immediately. Only successful transactions get applied. Therefore, it may take a while until your changes take effect!

Warning

The home-manager module assumes that flatpak is usable on your system. If this is not the case, do not bug report.

Caution

Expect at least a 2x storage usage increase. This module attempts to optimize storage space use through reflinks, these require a filesystem capable of Copy-on-Write.

Also try https://github.com/gmodena/nix-flatpak

Versioning

Releases are done through git tags.

Setup

Inputs

Flakes

flake.nix

{
  inputs = {
    flatpaks.url = "github:in-a-dil-emma/declarative-flatpak/latest";
  };
}

npins

console

$ npins add github --name flatpaks in-a-dil-emma declarative-flatpak

Import in NixOS

Flakes

configuration.nix

{ flatpaks, ... }: {
  imports = [
    flatpaks.nixosModules.default
  ];
}

npins

configuration.nix

{ flatpaks, ... }: {
  imports = [
    (flatpaks + "/nixos")
  ];
}

Import in Home Manager (standalone or as a NixOS module)

Flakes

home.nix

{ flatpaks, ... }: {
  imports = [
    flatpaks.homeModules.default
  ];
}

npins

home.nix

{ flatpaks, ... }: {
  imports = [
    (flatpaks + "/home-manager")
  ];
}

Configuring

services → flatpak

OPTION	TYPE	DEFAULT
enable	boolean	false
preRemotesCommand	string or null	null
preInstallCommand	string or null	null
preSwitchCommand	string or null	null
UNCHECKEDfinalizeCommand	string or null	null
flatpakDir	path or null	NixOS: /var/lib/flatpak ; Home-Manager: ${XDG_DATA_HOME}/flatpak
forceRunOnActivation	boolean	false
onCalendar	systemd time	weekly

Caution:

UNCHECKEDfinalizeCommand will not cause the transaction to fail. This hook should only be used for commands you don't care about failing.

... → packages → list element

list element is a string, matching one of the following patterns:

• {remote}:{type}/{ref}/[{arch}]/{branch}[:{commit}]
• {remote}:{path}.flatpakref
• :{path}.flatpak

Expressions in [angle brackets] may be omitted. Expressions in {curly brackets} must be substituted.

KEY	SUBSTITUTION DESCRIPTION
remote	The remote to fetch from.
type	Ref type. Either app or runtime.
ref	Ref ID used by flatpak.
arch	System architecture, in flatpak's format.
branch	Ref release branch.
commit	Update to commit. Must be exactly 64 characters long.
path	A path that exists.

... → remotes → key-value pair

KEY	VALUE
Name	URL

... → overrides → key-value pair

KEY	VALUE
Filename	See https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak-metadata

Example configuration.

{
  services.flatpak = {
    enable = true;
    remotes = {
      "flathub" = "https://dl.flathub.org/repo/flathub.flatpakrepo";
      "flathub-beta" = "https://dl.flathub.org/beta-repo/flathub-beta.flatpakrepo";
    };
    packages = [
      "flathub:app/org.kde.index//stable"
      "flathub-beta:app/org.kde.kdenlive/x86_64/stable"
      ":${./foobar.flatpak}"
      "flathub:/root/testflatpak.flatpakref"
    ];
    overrides = {
      # note: "global" is a flatpak thing
      # if you ever ran "flatpak override" without specifying a ref you will know
      "global".Context = {
        filesystems = [
          "home"
        ];
        sockets = [
          "!x11"
          "!fallback-x11"
        ];
      };
      "org.mozilla.Firefox" = {
        Environment = {
          "MOZ_ENABLE_WAYLAND" = 1;
        };
        Context.sockets = [
          "!wayland"
          "!fallback-x11"
          "x11"
        ];
      };
    };
  };
}

Please consult the module options for more information.