nix-flatpak

Unlike purely declarative systems, nix-flatpak follows a convergent mode approach. This means the target system state description is not exhaustive; there is room for divergence across builds and rollbacks.

This approach allows for flexibility, such as tracking the latest versions of desktop applications or allowing them to auto-update, which is a tradeoff against absolute system reproducibility.

Note on performance: Flatpak applications are installed via a systemd oneshot service triggered at system activation. If you have a large number of applications, this may significantly increase your system's activation time.

If you are not using Flakes, you can manually fetch nix-flatpak using pkgs.fetchFromGitHub. You will need to provide the correct rev (version tag) and hash.

You can generate the required hash using the nix-prefetch-github command:

nix-prefetch-github gmodena nix-flatpak --rev <rev>

let
  nix-flatpak = pkgs.fetchFromGitHub {
    owner = "gmodena";
    repo = "nix-flatpak";
    rev = "v0.7.0";
    hash = "sha256-7ZCulYUD9RmJIDULTRkGLSW1faMpDlPKcbWJLYHoXcs=";
  };
in
  imports = [ "${nix-flatpak}/modules/nixos.nix" ];

When using services.flatpak.overrides.files, the method of referencing files affects whether your configuration is 'pure':

• Impure (String paths): Using a string like "/home/user/overrides/app.ini" requires passing --impure to nixos-rebuild because the file is read from the filesystem at evaluation time.
• Pure (Nix path literals): Using a path literal like ./overrides/app.ini copies the file into the Nix store during evaluation, making the configuration reproducible and pure.

Note: writeMode = "replace" with only settings (no files) is always pure.

# Required if using string paths in overrides.files
sudo nixos-rebuild switch --impure

Bundle files (.flatpak) can be installed by pointing the bundle attribute to a URI (using pkgs.fetchurl) or a local file path. A sha256 hash is required.

# From a URI
services.flatpak.packages = [
  rec {
    appId = "<appId>";
    sha256 = "<hash>";
    bundle = "${pkgs.fetchurl {
      url = "<bundle-uri>";
      inherit sha256;
    }}";
  }
];

# From a local file
services.flatpak.packages = [
  {
    bundle = "file:///path/to/local/app.flatpak";
    appId = "<appId>";
    sha256 = "<hash>";
  }
];

By default, nix-flatpak only manages packages and remotes explicitly declared in your configuration. Packages installed via app stores or CLI will be ignored.

To make nix-flatpak manage the entire lifecycle (including uninstallation of undeclared items), set services.flatpak.uninstallUnmanaged = true.

Scope:

• If installed as a HomeManager module, it only affects user installations (~/.local/share/flatpak/).
• If installed as a NixOS module, it only affects system installations (/var/lib/flatpak/).

By default, when you remove an override from your Nix configuration, the corresponding file on disk is preserved. To ensure a clean state where only declared overrides exist, set services.flatpak.overrides.pruneUnmanagedOverrides = true;.

Warning: This can result in data loss if you have manual overrides you intended to keep. Use with caution.

You can control how and when Flatpak applications are updated:

1. On Activation: Set services.flatpak.update.onActivation = true; to update during system/user activation. The default is false to ensure idempotency.
2. Periodic Updates: Enable scheduled updates via services.flatpak.update.auto. This uses systemd timers. onCalendar accepts standard systemd timer expressions.

# Update on activation
services.flatpak.update.onActivation = true;

# Periodic updates
services.flatpak.update.auto = {
  enable = true;
  onCalendar = "weekly";
};

You can install applications using .flatpakref files by setting the flatpakref attribute. A sha256 hash is required. If omitted, the flake evaluation will require the --impure flag.

When installing via flatpakref, the remote is determined by the SuggestRemoteName key in the file, or by sanitizing the Name key if no suggestion exists.

services.flatpak.packages = [
  { flatpakref = "<uri>"; sha256="<hash>"; }
];