Filesystem

This page describes the typical filesystem inside a Flatpak sandbox.

Flatpak can operate on system-wide and per-user installations. System-wide installations end up in /var/lib/flatpak, while per-user installations end up in $HOME/.local/share/flatpak. After installing org.gnome.Platform and org.gnome.GEdit (with --user), the downloaded runtime and application data ends up in $HOME/.local/share/flatpak and $HOME/.var:

.local/share/flatpak/
├── repo
│   ├── config
│   ├── objects
│   │   ├── 00
│   │   ┊
│   │   └── ff
│   ├── refs
│   │   ├── heads
│   │   └── remotes
│   │       └── test-repo
│   └── state
├── runtime
│   └── org.gnome.Platform
│       └── x86_64
│           └── 3.14
│               ├── active -> 71885e962e0daa8635cc7f33…
│               ├── 71885e962e0daa8635cc7f33…
│               │   ├── files
│               │   │   └┈
│               │   └── metadata
│               └── origin
├── app
│   └── org.gnome.GEdit
│       ├── current -> x86_64/master
│       └── x86_64
│           └── master
│               ├── active -> cf22ec5c375bba629b33385a…
│               ├── cf22ec5c375bba629b33385a…
│               │   ├── export
│               │   │   └┈
│               │   ├── files
│               │   │   └┈
│               │   └── metadata
│               └── origin
└── exports
    └── share
        ├── applications
        ├── dbus-1
        └── icons
.var/
└── app
    └── org.gnome.GEdit
        ├── data
        ├── config
        └── cache

The filesystem layout for installed application is very simple. System-wide applications are found in /var/lib/flatpak/app/, per-user applications are in $HOME/.local/share/flatpak/app/. Each application is contained in subdirectories of the form name/arch/branch, so if multiple branches or architectures of the same application are installed, they will share some of these directories. Below the branch/ directory, there is an origin file which contains the name of the remote for this application and an active/ subdirectory which contains the data that makes up the application:

• The files/ subdirectory contains the application files. Inside the sandbox, the files/ subdirectory gets mounted at /app, so the application should be built for the prefix "/app".
• The export/ subdirectory contains files that are needed outside the sandbox by the host system to make the application available to the user (typically the desktop file, application icon, D-Bus service files, etc). These files get symlinked to the "toplevel" exports/ directory during installation (e.g. ~/.local/share/flatpak/exports/ for per-user applications).
• The metadata file contains information about the application that is used in setting up the sandbox (including what runtime it uses).

The filesystem layout for runtimes is very similar. System-wide runtimes are found in /var/lib/flatpak/runtime/, per-user runtimes are in $HOME/.local/share/flatpak/runtime/. As for applications, each runtime is contained in subdirectories of the form name/arch/branch, with an origin file and an active/ subdirectory below that contains the data of the runtime:

• The files/ subdirectory contains the runtime files. It gets mounted at /usr in the sandbox of applications using the runtime. Note that runtimes alway use /usr/lib/ - there's no need for multilib in a system where each application can use its own, separate runtime.
• Optionally, runtimes can have a metadata file as well.

In addition to /app and /usr, each application sandbox gets a per-app data directory mounted which persists over app upgrades. It is stored as a subdirectory of the $HOME/.var/app directory (e.g. $HOME/.var/app/org.gnome.GEdit/). The $XDG_DATA_HOME, $XDG_CONFIG_HOME and $XDG_CACHE_HOME environment variables are set to point at data/, config/ and cache/ subdirectories respectively in this location.

Flatpak uses OSTree to distribute and manage applications and runtimes. The repo/ in the above tree is the local OSTree repository. Flatpak creates the active/ directories of applications and runtimes as symlinks to OSTree checkouts (in the same directory). Using OSTree has the advantage that the checkouts are automatically deduped and share diskspace, since OSTree is using hardlinks and content-based addressing. OSTree also makes it easy to roll back to an earlier version, should the need arise. But the definition of the filesystem layout for applications and runtimes and the sandboxing implementation are not tied to OSTree in any way, and it is very possible to distribute runtimes and applications with a different mechanism.