{"id":14967969,"url":"https://github.com/gmodena/nix-flatpak","last_synced_at":"2025-05-15T20:05:41.887Z","repository":{"id":202912510,"uuid":"706844687","full_name":"gmodena/nix-flatpak","owner":"gmodena","description":"Install flatpaks declaratively","archived":false,"fork":false,"pushed_at":"2025-03-15T08:59:32.000Z","size":169,"stargazers_count":469,"open_issues_count":14,"forks_count":16,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-08T06:35:37.583Z","etag":null,"topics":["flatpak","nixos"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmodena.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-18T18:17:22.000Z","updated_at":"2025-04-02T21:15:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"a5e79b17-bf56-4771-92fa-a05c5c0001bd","html_url":"https://github.com/gmodena/nix-flatpak","commit_stats":{"total_commits":50,"total_committers":10,"mean_commits":5.0,"dds":0.24,"last_synced_commit":"8d1193a959c7810f01610c10a055b0020390bf4e"},"previous_names":["gmodena/nix-flatpak"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmodena%2Fnix-flatpak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmodena%2Fnix-flatpak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmodena%2Fnix-flatpak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmodena%2Fnix-flatpak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmodena","download_url":"https://codeload.github.com/gmodena/nix-flatpak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flatpak","nixos"],"created_at":"2024-09-24T13:39:02.503Z","updated_at":"2025-05-15T20:05:36.803Z","avatar_url":"https://github.com/gmodena.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![system build](https://github.com/gmodena/nix-flatpak/actions/workflows/test.yml/badge.svg)](https://github.com/gmodena/nix-flatpak/actions/workflows/test.yml)\n\n# nix-flatpak\n\nDeclarative flatpak manager for NixOS inspired by [declarative-flatpak](https://github.com/GermanBread/declarative-flatpak) and nix-darwin's [homebrew](https://github.com/LnL7/nix-darwin/blob/master/modules/homebrew.nix) module.\nNixOs and home-manager modules are provided for system wide or user flatpaks installation.\n\n## Versioning\n\nWe use Git tags and branches to manage versions:\n\n- **`0.6.0`** → Current stable release.\n- **`latest`** → Always points to the most recent stable version (`0.6.0` as of now).\n- **`main`** → Unstable, development branch.\n\n\nThis project is released as a [flake](https://nixos.wiki/wiki/Flakes), and is published\non [flakehub](https://flakehub.com/flake/gmodena/nix-flatpak).\n\n\n## Background\n\nThis project was inspired by  Martin Wimpress' [Blending NixOS with Flathub for friends and family](https://talks.nixcon.org/nixcon-2023/talk/MNUFFP/)\ntalk at NixCon 2023.\n\n`nix-flatpak` follows a [convergent mode](https://flyingcircus.io/blog/thoughts-on-systems-management-methods/) approach to package management (described in [this thread](https://discourse.nixos.org/t/feature-discussion-declarative-flatpak-configuration/26767/2)):\nthe target system state description is not exhaustive, and there's room for divergence across builds\nand rollbacks.\nFor a number of desktop applications I want to be able to track the latest version, or allow them to auto update.\nFor such applications, a convergent approach is a reasonable tradeoff wrt system reproducibility. YMMV.\n\nFlatpak applications are installed by systemd oneshot service triggered at system activation. Depending on\nthe number of applications to install, this could increase activation time significantly. \n\n### Manual installation\n\nReleases are tagged with [semantic versioning](https://semver.org/). Versions below `1.0.0` are considered early, development, releases.\nUsers can track a version by passing its release tag as `ref`\n```nix\n...\nnix-flatpak.url = \"github:gmodena/nix-flatpak/?ref=v0.6.0\";\n...\n```\n\nThe `latest` tag will always point to the most recent release.\n```nix\n...\nnix-flatpak.url = \"github:gmodena/nix-flatpak/?ref=latest\";\n...\n```\n\nThe `main` branch is considered unstable, and _might_ break installs.\n```nix\n...\nnix-flatpak.url = \"github:gmodena/nix-flatpak/\";\n...\n```\n\n### Starter config example\nYou can find an example configuration in [testing-base/flatpak.nix](https://github.com/gmodena/nix-flatpak/tree/main/testing-base).\n\n\n## Getting Started\n\nEnable flatpak in `configuration.nix`:\n```nix\nservices.flatpak.enable = true;\n```\n\nImport the module (`nixosModules.nix-flatpak` or `homeManagerModules.nix-flatpak`).\nUsing flake, installing `nix-flatpak` as a NixOs module would look something like this:\n\n```nix\n{\n  inputs = {\n    # ...\n    nix-flatpak.url = \"github:gmodena/nix-flatpak\"; # unstable branch. Use github:gmodena/nix-flatpak/?ref=\u003ctag\u003e to pin releases.\n  };\n\n  outputs = { nix-flatpak, ... }: {\n    nixosConfigurations.\u003chost\u003e = nixpkgs.lib.nixosSystem {\n      modules = [\n        nix-flatpak.nixosModules.nix-flatpak\n\n        ./configuration.nix\n      ];\n    };\n  };\n}\n\n```\n\nSee [flake.nix](https://github.com/gmodena/nix-flatpak/blob/main/testing-base/flake.nix) in [testing-base](https://github.com/gmodena/nix-flatpak/tree/main/testing-base) for examples of setting up `nix-flatpak` as a NixOs and HomeManager module.\n\n## Notes on HomeManager \nDepending on how config and inputs are derived `homeManagerModules` import can be flaky. Here's an example of how `homeManagerModules` is imported on my nixos systems config in [modules/home-manager/desktop/nixos/default.nix](https://github.com/gmodena/config/blob/5b3c1ce979881700f9f5ead88f2827f06143512f/modules/home-manager/desktop/nixos/default.nix#L17). `flake-inputs` is a special extra arg set in the repo `flake.nix`\n[mkNixosConfiguration](https://github.com/gmodena/config/blob/5b3c1ce979881700f9f5ead88f2827f06143512f/flake.nix#L29).\n \n### Remotes\nBy default `nix-flatpak` will add the flathub remote. Remotes can be manually\nconfigured via the `services.flatpak.remotes` option:\n\n```nix\nservices.flatpak.remotes = [{\n  name = \"flathub-beta\"; location = \"https://flathub.org/beta-repo/flathub-beta.flatpakrepo\";\n}];\n```\nNote that this declaration will override the default remote config value (`flathub`).\nIf you want to keep using `flathub`, you should explicitly declare it in the\n`services.flatpak.remotes` option.\n\nAlternatively, it is possible to merge declared remotes with the default one with `lib.mkDefaultOption`.\n```nix\n  services.flatpak.remotes = lib.mkOptionDefault [{\n    name = \"flathub-beta\";\n    location = \"https://flathub.org/beta-repo/flathub-beta.flatpakrepo\";\n  }];\n```\n\n### Packages\nDeclare packages to install with:\n```nix\n  services.flatpak.packages = [\n    { appId = \"com.brave.Browser\"; origin = \"flathub\";  }\n    \"com.obsproject.Studio\"\n    \"im.riot.Riot\"\n  ];\n```\nYou can pin a specific commit setting `commit=\u003chash\u003e` attribute.\n\nRebuild your system (or home-manager) for changes to take place.\n\n#### Flatpakref files\n[Flatpakref](https://docs.flatpak.org/en/latest/repositories.html#flatpakref-files) files can be installed by setting the `flatpakref` attribute to :\n```nix\n  services.flatpak.packages = [\n    { flatpakref = \"\u003curi\u003e\"; sha256=\"\u003chash\u003e\"; }\n  ];\n```\n\nA `sha256` hash is required for  the flatpakref file. This can be generated with `nix-prefetch-url \u003curi\u003e`.\nOmitting the `sha256` attribute will require an `impure` evaluation of the flake.\n\nWhen installing an application from a `flatpakref`, the application remote will be determined as follows:\n1. If the package does not specify an origin, use the remote name suggested by the flatpakref in `SuggestRemoteName`.\n2. If the flatpakref does not suggest a remote name, sanitize the flatpakref `Name` key with the same algo flatpak implements in [create_origin_remote_config()](https://github.com/flatpak/flatpak/blob/b730771bd793b34fb63fcbf292beed35476e5b92/common/flatpak-dir.c#L14423).\n\n##### Unmanaged packages and remotes\n\nBy default `nix-flatpak` will only manage (install/uninstall/update) packages declared in the\n`services.flatpak.packages` and repositories declared in `services.flatpak.remotes`.\nFlatpak packages and repositories installed by the command line of app stores won't be affected.\n\nSet `services.flatpak.uninstallUnmanaged = true` to alter this behaviour, and have `nix-flatpak` manage the\nlifecycle of all flatpaks packages and repositories.\n\nNote that `services.flatpak.uninstallUnmanaged` will only affect a given `system` of `user` installation\ntarget. If `nix-flatpak` is installed as a HomeManager module all packages/remotes will be managed\nin a `user` installation. Packages/remotes installed system-wide won't be affected\nby `services.flatpak.uninstallUnmanaged`.\n\nSimilarly, when `nix-flatpak` is installed as a NixOs module, only system-wide config will\nbe affected.\n\n### Updates\n\nSet\n```nix\nservices.flatpak.update.onActivation = true;\n```\nto enable updates at system activation. The default is `false`\nso that repeated invocations of `nixos-rebuild switch` are idempotent. Applications \npinned to a specific commit hash will not be updated.\n\nPeriodic updates can be enabled  by setting:\n```nix\nservices.flatpak.update.auto = {\n  enable = true;\n  onCalendar = \"weekly\"; # Default value\n};\n```\nAuto updates trigger on system activation.\n\nUnder the hood, updates are scheduled by realtime systemd timers. `onCalendar` accepts systemd's\n`update.auto.onCalendar` expressions. Timers are persisted across sleep / resume cycles.\nSee https://wiki.archlinux.org/title/systemd/Timers for more information. \n\n### Storage\nFlatpaks are stored out of nix store at `/var/lib/flatpak` and `${HOME}/.local/share/flatpak/` for system\n(`nixosModules`) and user (`homeManagerModules`) installation respectively. \nFlatpaks installation are not generational: upon a system rebuild and rollbacks, changes in packages declaration\nwill result in downloading applications anew.\n\nKeeping flatpaks and nix store orthogonal is an explicit design choice, dictate by my use cases:\n1. I want to track the latest version of all installed applications.\n2. I am happy to trade network for storage.\n\nYMMV.\n\nIf you need generational builds, [declarative-flatpak](https://github.com/GermanBread/declarative-flatpak)\nmight be a better fit.\n\n### Overrides\n\nPackage overrides can be declared via `services.flatpak.overrides`. Following is a usage example:\n```nix\n{\n  services.flatpak.overrides = {\n    global = {\n      # Force Wayland by default\n      Context.sockets = [\"wayland\" \"!x11\" \"!fallback-x11\"];\n\n      Environment = {\n        # Fix un-themed cursor in some Wayland apps\n        XCURSOR_PATH = \"/run/host/user-share/icons:/run/host/share/icons\";\n\n        # Force correct theme for some GTK apps\n        GTK_THEME = \"Adwaita:dark\";\n      };\n    };\n\n    \"com.visualstudio.code\".Context = {\n      filesystems = [\n        \"xdg-config/git:ro\" # Expose user Git config\n        \"/run/current-system/sw/bin:ro\" # Expose NixOS managed software\n      ];\n      sockets = [\n        \"gpg-agent\" # Expose GPG agent\n        \"pcsc\" # Expose smart cards (i.e. YubiKey)\n      ];\n    };\n\n    \"org.onlyoffice.desktopeditors\".Context.sockets = [\"x11\"]; # No Wayland support\n  };\n}\n```\n\n### Systemd unit retry on error\nOn flaky network connections the `nix-flatpak` installer script may fail. \n\nThe `restartOnFailure` option controls the behavior of the flatpak-managed-install service when it encounters a failure. As of 0.6.0 it is enabled by default, and wraps systemd APIs. It's configuration can be modified by setting:\n```nix\nrestartOnFailure = {\n  enable = true;\n  restartDelay = \"60s\";\n  exponentialBackoff = {\n    enable = false;\n    steps = 10;\n    maxDelay = \"1h\";\n  };\n};\n```\n\nSee `module/options.nix` and systemd's own documentation for more details.\n\n# Known issues\n\nA couple of things to be aware of when working with `nix-flatpak`.\n\n## Infinite recursion in home-manager imports\n\nUsers have reported an infinite recursion stacktrace when importing an home-manager module outside of where home-manager\nitself was imported.\n\nTo work around this issue, you should avoid nesting home-manager modules. This means that when you are structuring your configuration, make sure that you do not have home-manager modules imported within each other in a way that could lead to circular imports.\n\nYou can follow the discussions and updates on issue [#25](https://github.com/gmodena/nix-flatpak/issues/25) to stay informed about any resolutions or workarounds.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmodena%2Fnix-flatpak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmodena%2Fnix-flatpak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmodena%2Fnix-flatpak/lists"}