Flatpak Template Installation (Updated November 2025)

Community Guides
1

Flatpak Template Installation (Updated November 2025)

Target: Debian 12/13 - XFCE template

Disclaimer: This guide resolves the problems I encountered installing Flatpak support in my templates while reasonably adhering to current Qubes OS security guidelines. The guide covers installing Flatpak containers in the system workspace (templateVM) and in user space (AppVM, StandaloneVM). This guide aims to be as simple and user-friendly as possible.

Thanks to KitsuneNoBaka and solene for their help.

Note: It is assumed that the user is already familiar with Qubes OS and its security approach (necessary restrictions) when manipulating system components!

Steps to follow:

For Debian XFCE Template

(Assumes Qubes OS configuration - anonymous updates - proxy - sys-Whonix enabled)

  • Start the template.

  • Open the Synaptic Package Manager.

  • Install the Gnome Store and Flatpak support packages:

    gnome-software
gnome-software-common
gnome-software-plugin-flatpak
libflatpak0

  • End of installation

Flatpak configuration in the system template (immutable)

  • Open a system terminal

  • Enter the following commands:

export all_proxy=http://127.0.0.1:8082/

#This opens a communication channel through the sys-Whonix proxy connection

flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

#This adds a temporary Flatpak repository address (config.system)

  • Enable communication from the proxy for updating the application catalog in the Gnome Store with the command:
export http_proxy=http://127.0.0.1:8082/
  • Launch the GNOME Software Store from the same terminal with the command:
gnome-software

  • Install your chosen Flatpak apps

  • Enjoy :slight_smile:

The template should now be able to install any Flatpak app and be deployed without changes persisting outside the template.

Flatpak configuration in a user space (deployment for persistence in AppVM Qubes)

  • Repeat the GNOME Store and Flatpak installation steps using the Synaptic package manager.

  • Close the template.

The rest of the configuration and app installation must be done from an AppVM or StandaloneVM created from the template.

  • Create an AppVM or StandaloneVM from the flatpak-user template created.

  • Open a system terminal.

  • Enter the command:

flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

#This adds the Flatpak repository address (user space configuration)

  • Open the GNOME Store from the same terminal with the command:
gnome-software

#The store should now display the applications from the Debian repository and include the Flathub catalog. The goal is to ensure that in the installation source selector in the upper right corner, alongside the traditional (deb) option, the option for (flatpak) should appear, but with the label “user.” This means that the app will be installed in the user space of the AppVM and will remain even after the qube is restarted.

  • Install apps.

  • Enjoy :slight_smile:

Manual update of the Flatpak container and runtime

  • Updating Flatpak installed in system space must be done from the template in this installation mode.

Note: It is recommended to disable the automatic updates option in the GNOME Store for template mode, as changes will not persist in Qubes created from them and will only be a waste of internet bandwidth.

  • For user space installations, this must be done from each Qube separately where apps were installed.

To update manually in all cases, run the command in a terminal:

flatpak upgrade -y
  • End of guide.

Regards,

3 Likes
2

Thanks for posting this :blush:

1 Like
3

I don’t see any consistent differences between your guide and solene’s one… What am I missing?

Using wrong markdown markup makes things harder to read.

4

I don’t think mine was posted on the forum, and my instructions are maybe less compact and explicit.

1 Like
5

Honestly, thinking about this recently, we should ship a script to run that does all the steps to install flatpak and deploy flathub.

4 Likes
6

The following steps were not included in your guide @solene, at least not explicitly.

I double-checked my debian-12-xfce (flatpak) template and these packages are not installed. Instead(?) org.gnome.platform was installed by flatpak. It would be helpful to know if this step should be included in Solene’s guide as well.

1 Like
7

Hi, thanks for the explanation. What you’re saying makes me think you installed the Flatpak system and its runtimes externally. If you’re not using the Gnome store, where do you see the Flatpak repository?

8

Hi, I initially followed Solene’s guide, but the installation failed. Another colleague, Kitsunenobaka, helped me fix the problem. Apparently, Solene’s guide is for older versions of Gnome because it includes extra steps that are currently unnecessary. So, to prevent others from getting stuck like I did, I shared my experience with Flatpak. I also want to thank those who helped me in this guide. Cheers.

2 Likes
9

I believe it would be appropriate for the Qubes OS team to include the ability to deploy Flatpak for the relevant templates within the Qubes installation itself.

I’m not particularly in favor of making a habit of using third-party scripts, but if you do, I’d like to include a link to the post and put it at the beginning of this guide.

I’d like to see how to do something like this that replaces Synaptic’s function while respecting Qubes’ security guidelines for not using dangerous commands like “apt install” on Debian, and hopefully without having to copy anything to dom0.

10

This would be considered a change compared to the upstream distribution, the development team sticks to upstream as much as possible.

And if flathub was added by default, you would read from a lot of users complaining that flathub is enabled by default.

11

I just visit the Flathub website (flathub.org), search for the app, copy the app id from the install menu, and run the following command in the template:

flatpak install flathub <app id>
12

Don’t do it by default, but as an option like everything else in the settings for what type of templates you want to install. Sorry, I thought that was understood, but in the end it’s the development team’s decision.

13

Now I understand, I’m sorry but I find that process a bit cumbersome; instead I prefer to use the Gnome store catalog since that’s what it’s for.