How to back up Flatpak user-data and apps

You’ll probably want to make some changes to your home directory backup script after adopting and installing a few Flatpak applications. Here are the things you’ll need to think about.

There are three things you need to back up everything in Flatpak: your user settings and data, the list of installed apps, and the repositories configuration so Flatpak will know where to install apps from.

Backing up user-data

Backing up and restoring user-data is as easy as copying the files from the per-application data directories that Flatpak assigns to each app.

Flatpak stores user data in $HOME/.var/app/ for confined apps. Some apps may have access to and writes to directories in your home directory. You’ll need to investigate which apps have access to write to the home directory and which stick to their per-application Flatpak directory to be sure you backup all required data. With time, more applications are expected to be confined to their per-application directory.

You should exclude the $HOME/.var/app/*/cache/ directories which are equivalent to the $XDG_CACHE_HOME ($HOME/.cache/) directory for regular applications. The first and second section of my article on Steam and XDG in Flatpak explains how XDG Base Directories are mapped in the Flatpak per-application user directory.

You should always verify that apps you care about are properly backed up.

Backing up repository configuration

It’s difficult to untangle the repository configuration from the installed app and runtime data, and the locally installed repository contents and metadata. If you’ve installed a few apps and runtimes, this data quickly grows to several Gigabytes. You generally don’t want to include this in your backup as this data isn’t unique and you can just download the data again given that the list of apps and repositories is known. I’ll get back to this point later.

If you’ve installed apps, runtimes, and repositories as --user all of this data ends up in the Flatpak installation directory at ~/.local/share/flatpak/. You can choose to back up this directory in its entirety, but you’ll probably want to exclude this directory to keep your backups small and storage costs down. I’ll assumed that you’ve installed everything as --user in this article. You’ll have to adjust the paths to the shared system directory at /var/lib/flatpak/ if you’ve installed things there instead.

As I mentioned initially, you unfortunately can’t backup the repository file and it’s signing key directly (~/.local/share/flatpak/repo/config and ./*.trustedkeys.gpg. Or rather, nothing is stopping you from backing up those files — but you can’t just move those files back on an empty Flatpak install directory on a new system. Flatpak expects and requires that its whole set of complex directories and certain large data files already exist. You must add repositories using the command-line utilities to set up the environment properly.

The script in this section requires Flatpak version 0.10.4 or later, and it relies on an unstable interfaces which may change.

The following example script exports a list of your repositories as a list of commands that you can execute to reinstall your Flatpak repositories. You can pipe send the output list to a file as part of your backup script.

flatpak remotes --show-details | awk '{print "echo \"echo \\\x22$(base64 --wrap=0 < $HOME/.local/share/flatpak/repo/" $1 ".trustedkeys.gpg)\\\x22 | base64 -d | flatpak remote-add --if-not-exists --gpg-import=- --prio=\\\x22"$4"\\\x22 --title=\\\x22"$2"\\\x22 --user \\\x22"$1"\\\x22 \\\x22"$3"\\\x22\""}' | sh

So … there’s a lot going on in that one script. The first part of the script prints a list of all the installed repositories excluding their signing signature. The next part finds the signing key and endcodes it in a format that can be stored as a string. The last part of the script constructs the import command with all the repository’s information and instructions to import the signature. The output is one command per repository that can be used to install the repository on fresh installation.

You also have to run flatpak update once after installing repositories to retrieve metadata.

Backing up the list of installed apps

Once you’ve backed up your repositories, you can also export and backup a list of which apps you’ve got installed.

The following example script exports a list of your installed apps as a list of commands that you can execute to reinstall your Flatpak apps after you’ll restored your repository list. You can send the output of the example command to a file as part of your backup script.

This script relies on an unstable interfaces which may change.

flatpak list --app --show-details | \
awk '{print "flatpak install --assumeyes --user \""$2"\" \""$1}' | \
cut -d "/" -f1 | awk '{print $0"\""}'

The script asks Flatpak to list of a detailed view of installed applications (this isn’t a stable interface!), and then constructs the commands required to reinstall them. Lastly it discards the version information so that you get the most recent version of the app when restoring it. Please note that the example script doesn’t handle multiple versions of the same app.

You can also export and import your list of apps using the stable interface provided in libflatpak. However, there are no clients that implement this interface for this purpose at .

I don’t recommend that anyone rely on these example scripts for backup purposes without regularly testing that their backups still work. They don’t use stable interfaces, and Flatpak is currently under heavy development. Things may — and I fully expect them to — break.

You can follow Flatpak issue #1356 if interested in seeing better export and backup functionality built-in to Flatpak. Or you may have a look at the stable interfaces in libflatpak if you wish to create a better backup utility (note that signing keys aren’t available through this API.)

I wrote this article to bring attention to Flatpak’s backup problems and to provide people with the means to export their data. Just because an app is stored in a container doesn’t mean you don’t also want to back up its data.