RetroDECK: Flatpak Directory Structure

RetroDECK is a Flatpak - a sandboxed bundle containing applications, configurations and supporting files.

RetroDECK Flatpak: User-Accessible Directories

Directory Name	Directory Path	Comment
`retrodeck/` (userdata) Directory	`<Dynamic Path>/retrodeck/`	Read more: RetroDECK: Userdata Directory Structure
`/.var/app/net.retrodeck.retrodeck` Directory	`~/.var/app/net.retrodeck.retrodeck`	Mapped as `/var` inside the Flatpak. Exposes configuration, cache and system data from the Flatpak environment.
`cache` Directory	`~/.var/app/net.retrodeck.retrodeck/cache/`	Stores cache files and temporary data for components.
`config` Directory	`~/.var/app/net.retrodeck.retrodeck/config/`	Contains copied configuration files for components.
`data` Directory	`~/.var/app/net.retrodeck.retrodeck/data/`	Stores data structures for components.
`config/retrodeck` Directory	`~/.var/app/net.retrodeck.retrodeck/config/retrodeck/`	Main configuration file: `retrodeck.cfg`.

Flatpak: General Directories

Directory Name	Local Path	System Path	Comment
Flatpak Runtimes	`~/.local/share/flatpak/runtime/`	`/var/lib/flatpak/runtime/`	Stores runtime libraries such as `org.kde.Platform`, `org.freedesktop.Platform`, `org.gnome.Platform`.
Flatpak Overrides	`~/.local/share/flatpak/overrides/`	`/var/lib/flatpak/overrides/`	Flatpak-specific overrides for sandboxed applications.

RetroDECK Flatpak Sandbox and Persistent Data

When accessing the Flatpak sandbox via the CLI in Debug Mode, internal directories such as /app and /var map to different locations on the host filesystem.

This is part of Flatpak's sandboxing model:

The application runtime under /app is read-only.
/var provides writable directories for persistent user data, such as configuration, cache and application-specific files.
RetroDECK also creates a user-defined userdata directory retrodeck/, which can be placed wherever the user chooses.

When the application is updated, the runtime under /app changes, but the writable data under /var (for example config, cache and data) remains mostly unchanged (depending on the update).

Because the retrodeck/ and /var directories are shared across versions and branches, regular backups are recommended, especially when testing beta or development builds that may modify configuration or data formats in both directories. Jumping from a bleeding-edge development build back to stable is not recommended.

See the RetroDECK Testing Guide for instructions on creating backups.

Internal Path	Host Path	Comment
`/app`	`~/.local/share/flatpak/app/net.retrodeck.retrodeck/current/active/files/` or `/var/lib/flatpak/app/net.retrodeck.retrodeck/current/active/files/`	Read-only runtime environment provided by the Flatpak package. Contains: `bin`, `lib`, `libexec`, `manifest-base-1.json`, `manifest.json`, `retrodeck`, `share`, `tools`.
`/var`	`~/.var/app/net.retrodeck.retrodeck/`	Writable portion of the sandbox. Contains application state directories such as `cache`, `config` and `data`.

XDG Base Directory Paths in Flatpak

The following table shows how XDG base directory variables map to their corresponding host paths.

These directories follow the XDG Base Directory Specification.

XDG Variable	Host Path	Comment
`XDG_CACHE_HOME`	`~/.var/app/net.retrodeck.retrodeck/cache/`	Cache directory. Corresponds to `$HOME/.cache` inside the Flatpak sandbox.
`XDG_CONFIG_HOME`	`~/.var/app/net.retrodeck.retrodeck/config/`	Configuration directory. Corresponds to `$HOME/.config` inside the Flatpak sandbox.
`XDG_DATA_HOME`	`~/.var/app/net.retrodeck.retrodeck/data/`	Application data directory. Corresponds to `$HOME/.local/share` inside the Flatpak sandbox.

Steam: Directory Structure

Directory Name	Directory Path	Comment
Steam Default Templates	`~/.steam/steam/controller_base/templates/`	RetroDECK injects Steam Input templates here.
Application Templates	`~/.steam/steam/steamapps/common/Steam Controller Configs/<AppID>/config/retrodeck/`	Temporary changes stored here if user modifies templates.
Steam Binding Icons	`~/.steam/steam/tenfoot/resource/images/library/controller/binding_icons/`	RetroDECK injects Steam Input icons here.