Skip to content


The default-flatpaks module can be used to install or uninstall Flatpaks from a configurable remote on every boot. It skips that operation if no changes are detected. This module first removes the Fedora Flatpaks remote and Flatpaks that come pre-installed in Fedora. A Flatpak remote is configured the first time the module is used, but it can be re-configured in subsequent usages of the module. If no Flatpak remote is specified, the module will default to using Flathub.

Flatpaks can either be installed system-wide or per-user. Per-user Flatpaks will be installed separately for every user on a system. Previously-installed flatpaks can also be removed.

The module uses the following scripts to handle flatpak setup:

  • /usr/bin/system-flatpak-setup
  • /usr/bin/user-flatpak-setup

The scripts are run on every boot by these services:

  • /usr/lib/systemd/system/system-flatpak-setup.service
  • /usr/lib/systemd/user/user-flatpak-setup-service

system-flatpak-setup uninstalls Fedora flatpaks, replaces Fedora repos with your repo choice, checks the Flatpak install/remove lists created by the module & performs the install/uninstall operation according to that. user-flatpak-setup does the same thing for user Flatpaks.

This module stores the Flatpak remote configuration and Flatpak install/remove lists in /usr/share/bluebuild/default-flatpaks/. There are two subdirectories, user and system corresponding with the install level of the Flatpaks and repositories. Each directory has text files containing the IDs of flatpaks to install and remove, plus a repo-info.yml containing the details of the Flatpak repository.

This module also supports disabling & enabling notifications.

Local modification

If a local user is not satisfied with default Flatpak installations and removals in the image, it is possible for them to make modifications to the default configuration through the configuration files located within this directory:


Folder structure is the same as talked about above, with system & user folders, install & remove files containing explanation on how those should be modified & what they do. The notifications file also contains this explanation for turning notifications on or off.

Known issues

Multiple repos inclusion is currently not supported (planned to implement in the future):

Flatpak runtimes are not supported due to technical difficulty in implementing those:

Example configuration

modules: # configured multiple times to highlight how options are overridden
- type: default-flatpaks
notify: true # Send notification after install/uninstall is finished (true/false)
# If no repo information is specified, Flathub will be used by default
repo-name: flathub
repo-title: "Flathub (system-wide)" # Optional; this sets the remote's user-facing name in graphical frontends like GNOME Software
- org.gnome.Loupe
- one.ablaze.floorp//lightning # This is an example of flatpak which has multiple branches in selection (flatpak//branch).
# Flatpak runtimes are not supported (like org.winehq.Wine//stable-23.08).
# Only normal flatpak applications are (like Floorp Lightning web browser in this example).
# Multiple install of same flatpaks with different branches is not supported.
- org.gnome.eog
# A flatpak repo can also be added without having to install flatpaks,
# as long as one of the repo- fields is present
repo-name: flathub
# Assuming that the above example is configured first in a recipe,
# a subsequent usage might look like this:
- type: default-flatpaks
# If the repo-* fields are omitted on the subsequent usage,
# the module will use the previously configured repo.
# Otherwise, it will overwrite the repo configuration.
- org.kde.kdenlive # this Flatpak is appended to the insta llist
# repo-name will overwrite the previously-configured repo-name for the user remote
repo-name: flathub-user
repo-title: "Flathub (User)