Managing flatpaks declaratively

nix-flatpak is an experiment inspired by Martin Wimpress’ Blending NixOS with Flathub for friends and family) talk at NixCon 2023. I liked the idea of managing NixOS desktop applications in a similar way as I do with homebrew casks on nix-darwin.

nix-flatpak follows a convergent mode approach to package management (described in this thread), and is somewhat limited (it will break reproducibility assumptions).

I’m a relatively new nix user and this project was started as an excuse to learn modules and their import system. I wanted to share it, might other folks have use case similar to mine.

Feedback and critiques are very much appreciated.



@gmodena - Thank you for starting the development of this module. Flatpaks are a key part of my computing set-up and something that I have been battling to add declaratively to my nix setup.

Is it possible to use your module in it’s current form without using flakes? Is it possible to import the code directly into configuration.nix?

I would very much appreciate if you could provide a code sample that shows if it is possible to import directly into configuration.nix.

I am at the start of my nix journey, but already I am convinced that your approach to flatpak management will fill a gap that currently exists in nix.

Thank you once again for commencing this development.

hey @nixpix; thanks for giving this project a go & for the encouraging words. Much appreciated.

You could try to clone the repo to a location relative to your configuration.nix, and import modules/nixos.nix directly. However, I suspect things will break.
I’ll sandbox some time to try this out the upcoming weekend.

For the time being, maybe you could have a look at a previous iteration of my nix config: flatpak: add module to declaratively install apps by gmodena · Pull Request #40 · gmodena/config · GitHub

Here I kept the flatpak (slightly different naming) module bundled with the rest of my configs - and I imported it from a relative path. The nix-flatpak flake grew out of this setup.

The example I just linked uses home manager:

imports = [../../default.nix ../../../flatpak/home-manager.nix ];

If you wanted to import the module in configuration.nix, you’d have to do so as:

imports = [ ./path/to/flatpak/modules/nixos.nix ]

Hope it helps and happy to chat further.

@gmodena Thank you for the pointers. The short version is that it worked! :grinning: :tada:

I am writing in a bit more detail as much to document my progress but also for others who may look at this in the future.

I did what you said, specifically cloned the repo and imported it from a relative path into my configuration.nix file. I then ran sudo nixos-rebuild switch and the system rebuilt with the 3 example flatpaks that you had specified being installed. For anyone else reading this, the rebuild took far longer than usual with no visual feedback. This was due to the initial download of the flatpaks and the progress not being reported in the standard nix rebuild log. However you can confirm the download activity by monitoring network downloads during the rebuild.

I confirmed that the flatpaks were installed both by checking the applications’ icons had been installed and also running flatpak list. Both of these showed that indeed the flatpaks had been installed correctly.

The next thing I tried to do was to uninstall a flatpak by removing the reference to it from my configuration.nix file. I then rebuilt the system but unfortunately the flatpak remained installed. FYI I did try rebooting the system as well, but the installed flatpak remained installed despite being removed from the configuration.nix file.

I have two subsequent questions:

  1. Is the inability to uninstall a flatpak a limitation of the flatpak module or is there something else I need to do in addition to the usual deletion of the item from configuration.nix and rebuilding?
  2. Will flatpaks installed via the flatpak module automatically be updated during a nix rebuild if a new version is available on flathub (I have not pinned any specific versions and just did my testing using the three examples you used namely Brave Browser, Logseq ad Element/Riot)?

Once again thank you for your development, work and assistance. I personally feel that the addition of declarative flatpaks to nix is something that will be of immense value to the wider community.

1 Like

Hey @nixpix; happy to hear you go the module working!

Regarding your questions: I should have made things more clear in the doc. Currently you can install packages declaratively, but uninstall/updates are left as a manual operation.

I’m working on both aspects (it’s something I need myself), and have done some exploration on how to best integrate flatpak lifecycle management with nix generation management.

It is straightforward to compare installed apps vs declared list at build time and uninstall accordingly. However the flatpak installation live outside the nix store, so we won’t be rollback to a previous generation of flaptaks by swapping symlinks. This can make the semantic of rollbacks a bit murky.

I’ve been reviewing how appimage and casks (nix-darwin) are managed;

The design I’m settling on is to keep flatpaks orthogonal to nix store generations, but I’ll need some more experiments with rollbacks before merging changes. I’m learning the ropes myself :slight_smile:

Thanks for the valuable feedback, and apologies for the confusion. I created two issues to track your input at:

Hey, I think this is a great module. Unfortunately I didn’t get it to work in my Configs. I added the Input to my flake.nix and imported the module in my home.nix, but I get this Error: error: infinite recursion encountered
I didn’t have much experience yet, with flakes and modules and don’t know what I did wrong, so maybe someone here know what is wrong, here is the Link to my home.nix and flake.nix:
On my system are of course more files and directories within my Configs, but I think, the only two files that are needed, are these two. Maybe someone here finds out, what I did wrong and can help me

I’ve been looking for a declarative flatpak module for some time, so thanks for that!

But how does it differ from the declatarive-flatpak module you mentioned, so I can know which suits my use case better?

How do you declare the flake-inputs param passed to home.nix?

Infinite recursion errors are hard to debug without knowing the full config context. FWIW I too use the module with home-manager, and this is how I set up the relevant inputs bits in my config flake:

To be honest I don‘t know exactly what you mean with declare in this context. I added the Things in my flake.nix, but I didn‘t have the Line with homeManafer.extraArgs and in Home-Manager I added at the beginning flake-inputs and under import I put the flake-inputs.whatever Line and under the import I added the thing with services. flatpak. All other config Files, didn‘t have the flake-inputs at all and in none of the other Configs is the import of nix-flatpak nor the services.flatpak. Sorry that the Text isn‘t the best rn I‘m on my Smartphone at the Moment

But how does it differ from the declatarive-flatpak module you mentioned, so I can know which suits my use case better?

I’d say declarative-flatpak is more feature rich (and possibly battle tested) right now.

I don’t have hands on experience with that module, but looking at the doc the main differences are:

  1. different APIs for declaring package and remote configs.
  2. support for generational installs. From what I understand declarative-flatpak keeps the previous generation of applications around (doubling the storage required for the flatpak installation).

Re 1: I’m looking for something similar to the nix-darwin homebrew UX.
Re 2: for my use case I don’t care about keeping previous flatpak generations around. I’d be more interested in a rolling release approach, and in general I’m more constrained by disk space than bandwidth.

Hard to tell what’s going on without a stack trace. Can you narrow down where the infinite recursion happens (nix flake check --show-trace)?

Could you maybe try configuring home-manager.extraSpecialArgs.flake-inputs in your flake.nix as:

          modules = [
              home-manager = {
                useUserPackages = true;
                useGlobalPkgs = false;
                # Pass flake-inputs to home-nix excplicitely
                extraSpecialArgs = {
                    flake-inputs = inputs;
                users.bella = ./home/bella/home.nix;
            {programs.hyprland.enable = true;}

Disclaimer: I did not try this snippet.

It worked now, the Problem was the missing snippet in extraSpecialArgs

@gmodena, your module has inspired me to revisit my configs and I now have flakes working. I am working through rebuilding a more structured setup.

Irrespective of which direction you decide to take the module development, one other item that would be great to consider is including a status update as part of the rebuild. As I mentioned, at the moment, the rebuild works perfectly but there is no indication on the screen that flatpaks are being installed. Ideally we would be able to see installation progress (as you do when installing flatpaks natively) but even just a message on the screen noting that “flatpaks are being installed” would be helpful to new users of the module.

Please keep up the development. This is indeed a gem.

1 Like

Hi @Bella109 can you please post your working config?

I have just swapped over to using flakes and I am not able to get this working. Prior to using flakes I simply cloned the entire “nix=flatpak” repo locally (as per @gmodena’s instructions) and imported it into my configuration.nix file. I am now trying to include the github module in my new set-up and I am battling. Having a chance to see your working code will likely provide a template that I can use to enable it on my system. Thank you.

Yeah no problem here are the relevant Files

1 Like