nix-flatpak manages flatpaks declaratively, and says so

The module, and where the idea came from

nix-flatpak is described as a declarative flatpak manager for NixOS, and the README credits two direct inspirations, the declarative-flatpak project and the homebrew module in nix-darwin, which is the same idea applied to a different package format. NixOS and home-manager modules are provided for system wide or per user flatpak installation. There is also a story behind the project, since it was inspired by a NixCon 2023 talk on blending NixOS with Flathub for friends and family, and the implementation details and the origin story are covered in a later talk, Flatpaks The Nix Way, at NixCon 2025 with slides linked. That lineage explains the shape of the design.

Convergent mode, and what it gives up

The README is explicit that nix-flatpak follows a convergent mode approach to package management, and the explanation of what that means is the most useful paragraph in the documentation. The target system state description is not exhaustive, and there is room for divergence across builds and rollbacks. For a number of desktop applications the author wants to be able to track the latest version, or to allow them to auto update, and for such applications a convergent approach is described as a reasonable trade-off with respect to system reproducibility, with the note that your mileage may vary. That is an honest framing of the deal. A flatpak installed this way is not a build artifact of your configuration, it is whatever the remote serves at the time the service runs, and a rollback of your system configuration will not necessarily roll back the application version.

The cost is measured in activation time

The implementation detail that decides whether this suits your machine is stated in one sentence. Flatpak applications are installed by a systemd oneshot service triggered at system activation, and depending on the number of applications to install, this could increase activation time significantly. That is the whole cost model, and it is worth thinking about before enabling the module on a laptop that has to boot quickly. The installation runs at system activation, so enabling the module or adding applications makes the next activation slower. The module does not attempt to make the applications part of the system build, so the Nix store stays small and the flatpaks live in their own sandboxed runtime, which is the trade for not having to rebuild flatpak packages in Nix.

Versioning through tags, latest and main

Versions are managed with Git tags and branches, and there are three of them. The 0.8.0 tag is the current stable release, the latest tag always points to the most recent stable version, and main is the unstable development branch. Releases are tagged with semantic versioning, and versions below 1.0.0 are considered early development releases, so the current one carries a warning. Tracking a specific version is done by passing the release tag as the ref parameter in the flake URL:

nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=v0.8.0";

The latest tag points at the most recent release:

nix-flatpak.url = "github:gmodena/nix-flatpak/?ref=latest";

and the main branch is considered unstable and might break installs:

nix-flatpak.url = "github:gmodena/nix-flatpak/";

The project is released as a flake and is published on flakehub and on flakestry, so a flake consumer can reference it from either registry rather than only from GitHub.

Flakes are the front door, modules are the reality

Flakes are the recommended and officially supported installation method, but under the hood nix-flatpak is just a Nix module, and it is not available in channels, so it has to be downloaded and imported by hand. Nixpkgs users use the fetchFromGithub fetcher, and the package hash can be generated with nix-prefetch-github against the revision you want. A minimal configuration looks like this:

services.flatpak = {
  enable = true;
  packages = [
    "org.mozilla.firefox"
  ];
};

Under the hood the module is imported from the modules directory, with a NixOS module for system wide installation and a home-manager module for per user installation, and the README points at a gist with a minimal configuration that can be built and tested in a NixOS VM with nix-build. A starter configuration also lives in the repository under testing-base, and the flake.nix there shows the same thing set up for both NixOS and home-manager.

Remotes, packages and pinning a commit

By default nix-flatpak adds the flathub remote, and remotes can be configured manually through the services.flatpak.remotes option:

services.flatpak.remotes = [{
  name = "flathub-beta"; location = "https://flathub.org/beta-repo/flathub-beta.flatpakrepo";
}];

The documentation is careful about what that declaration does, because it overrides the default remote configuration rather than adding to it, so if you want to keep using flathub you have to declare it explicitly, and if you would rather merge your own remotes with the default one there is the lib.mkOptionDefault route. Packages are declared as a list of application ids, optionally with an origin and a commit, and the commit attribute pins a specific build of the flatpak:

services.flatpak.packages = [
  { appId = "com.brave.Browser"; origin = "flathub";  }
  "com.obsproject.Studio"
  "im.riot.Riot"
];

After changing the configuration you rebuild the system, or the home-manager configuration, for the changes to take place. The README also covers flatpakref files, which is the format for pointing at a flatpak that is not in a remote.

The state of the project, and one caveat

The releases are v0.8.0 published on 2026-10-10, v0.7.0 on 2026-01-09 and v0.6.0 on 2025-02-13, so the releases have stayed roughly nine to eleven months apart, and the last push was on 2026-10-10. The repository is not archived, the licence is Apache-2.0, and the tree is small, with a flake.nix, a modules/ directory, a test.sh, a tests/ directory, a testing-base/ directory and a CONTRIBUTORS.md. The caveat worth flagging is in the home-manager notes, where the README says that depending on how the configuration and inputs are derived, the homeManagerModules import can be flaky, and it points at the author's own configuration to show how the import is done there in practice, with a special extra argument set in the flake.nix to make it work. That is a small but real warning, because it means the home-manager path is less settled than the NixOS one.

Editorial conclusion

nix-flatpak fits a NixOS or home-manager user who wants the flatpak list to live in the same configuration file as everything else and who accepts that the applications will not be pinned to exact versions, because the module installs them through a systemd service at activation rather than through the Nix store. It does not fit a user who wants byte for byte reproducibility of their desktop, since the convergent model means the installed flatpak can differ between builds and rollbacks. It does not fit a setup that wants a specific flatpak commit pinned without extra work, though the commit attribute exists for that. Before you enable it, read the activation time note, because every application is installed by a oneshot service at boot and a large list will slow system activation down.

Frequently asked questions

Official sources

1. gmodena/nix-flatpak on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases