When your desktop looks perfect but your apps look broken
You install a new Flatpak application. You launch it. The window opens with a bright white background, chunky gray buttons, and a font that looks like it shipped with a desktop environment from a decade ago. The rest of your system is dark, sleek, and perfectly themed. The mismatch is jarring. You did not expect a modern package format to break your carefully curated appearance.
How the sandbox isolates your theme files
Flatpak applications run inside a sandbox. The sandbox isolates the application from the host filesystem for security and reproducibility. That isolation applies to theme files as well. When a Flatpak starts, it mounts a read-only runtime environment. The runtime contains the libraries the app needs, plus a default set of themes. It does not automatically scan your host ~/.themes directory or your system /usr/share/themes path. The app only sees what the runtime provides.
Think of the runtime like a pre-configured hotel room. The guest gets the amenities that came with the room. If you want different towels, you have to request them through the hotel's official supply chain, or you have to ask the front desk to let you bring your own. Flatpak uses the same model. The supply chain is the extension system. The front desk is the override mechanism.
The runtime version matters. Every Flatpak app declares a dependency on a specific platform runtime, such as org.gnome.Platform//45 or org.kde.Platform//6.5. The runtime version locks the library versions, the default theme, and the extension compatibility. Fedora's release cadence pushes runtime updates frequently, but your installed apps will keep using the runtime version they were built against until you explicitly update them. Run flatpak update regularly to keep runtimes aligned with your host system.
Check the runtime before you change anything. Guessing the version causes silent failures.
Align the appearance with the runtime
There are two reliable paths to align your Flatpak appearance with your host desktop. The first path installs the official theme extension that matches your runtime. The second path tells the sandbox to read your host theme directory directly. Both methods require terminal commands. Both methods persist across reboots.
Start by identifying which runtime your application uses. Run this command to list the runtimes currently installed on your system:
flatpak list --runtime
# WHY: Shows the exact runtime names and versions. Flatpak apps bind to a specific runtime like org.gnome.Platform//45 or org.kde.Platform//6.5.
# WHY: You must match the theme extension to this exact runtime version. A version mismatch causes the theme to silently fail.
# WHY: The output helps you verify which platform versions are actually present before installing extensions.
Once you know the runtime, install the matching theme extension. The GNOME platform ships with an official Adwaita extension, and KDE ships with a Breeze extension. Replace the version number in the command below with the version you found in the previous step:
flatpak install flathub org.gnome.Platform.Theme.Adwaita//46
# WHY: Downloads the official theme extension from Flathub.
# WHY: The //46 suffix binds this theme to the GNOME 46 runtime.
# WHY: Flatpak automatically activates extensions that match the runtime version.
# WHY: The extension unpacks into the runtime's read-only overlay, making the theme available to every app using that runtime.
If you prefer a custom theme that is not bundled in the official extensions, you need to grant the sandbox read access to your host theme directory. This approach works for any GTK or Qt theme you have installed on your system:
flatpak override --user --filesystem=~/.themes:ro
# WHY: Creates a user-level override for all Flatpak applications.
# WHY: The :ro flag grants read-only access to prevent apps from modifying your host themes.
# WHY: User-level overrides live in ~/.local/share/flatpak/overrides and survive system updates.
# WHY: Avoid --system unless you are managing a multi-user workstation where every account needs the same theme passthrough.
After applying either method, you may need to tell GTK applications which theme to load. Flatpak apps read their GTK configuration from a dedicated path inside the sandbox. Create the configuration file if it does not exist:
mkdir -p ~/.config/gtk-3.0
cat > ~/.config/gtk-3.0/settings.ini << 'EOF'
[Settings]
gtk-theme-name=Adwaita
gtk-icon-theme-name=Adwaita
EOF
# WHY: Creates the GTK 3 configuration directory if missing.
# WHY: Writes the theme and icon theme names into the settings file.
# WHY: Flatpak apps automatically mount this path from the host home directory.
# WHY: GTK 4 applications ignore this file entirely. They read the theme from the desktop environment's native settings instead.
Replace Adwaita with the exact name of your custom theme. The name must match the folder name inside ~/.themes. Restart the Flatpak application to apply the changes.
Apply the override before you launch the app. The sandbox reads the filesystem rules at startup.
Verify the theme loaded correctly
Open the application and check the window decorations and internal widgets. If the theme still looks wrong, verify that the extension is actually active. Run this command to inspect the active extensions for a specific runtime:
flatpak info --show-extensions org.gnome.Platform//46
# WHY: Lists every extension currently bound to the specified runtime.
# WHY: Confirms whether the theme extension loaded successfully or failed due to a version mismatch.
# WHY: The output shows the exact paths Flatpak uses, which helps you trace missing files.
If the extension appears in the list but the app still uses the default theme, the application might be using GTK 4 or Qt 6. GTK 4 ignores gtk-3.0/settings.ini entirely. Qt applications ignore GTK configuration files. You will need to adjust the approach based on the toolkit. Run flatpak info <app-id> to check the application's metadata and see which libraries it links against.
Check the runtime version first. A mismatched version is the most common reason themes fail to apply.
Common failure modes and what they look like
The most common failure mode is a runtime version mismatch. You install the GNOME 46 theme extension, but your application declares a dependency on the GNOME 45 runtime. Flatpak will not apply the 46 theme to the 45 runtime. The app falls back to the built-in default. Check the app manifest or run flatpak info <app-id> to see the exact runtime requirement.
Another frequent issue involves icon themes. The gtk-theme-name setting only changes window controls, buttons, and backgrounds. It does not change application icons. Icon themes require a separate extension or override. Run flatpak install flathub org.gnome.Platform.IconTheme.Adwaita//46 to fix missing or mismatched icons.
You may also encounter a blank theme or a broken interface if the theme name in settings.ini does not exactly match the directory name in ~/.themes. Flatpak does not perform fuzzy matching. A mismatched name causes the toolkit to silently revert to the runtime default. Verify the exact directory name with ls ~/.themes.
When the sandbox cannot find the theme files, the application prints a warning to standard error. You will see output like this when running the app from the terminal:
Gtk-WARNING: Failed to load module "canberra-gtk-module"
Gtk-Message: Failed to load theme "CustomDark": Theme engine not found
The warning confirms that the sandbox cannot locate the theme directory or the theme engine is missing from the runtime. Do not ignore these warnings. They point directly to the missing extension or the incorrect override path.
Read the stderr output before guessing. The toolkit tells you exactly which file it cannot find.
Choose the right method for your workflow
Use the official theme extension when you want a clean, version-locked setup that matches the runtime exactly. Use the host filesystem override when you rely on custom third-party themes that change frequently. Use the flatpak-theme community script when you want automatic theme synchronization across multiple runtimes without manual version tracking. Stay on the default runtime theme if you only use the application occasionally and do not care about visual consistency.
Pick the method that matches your update cadence. Manual overrides drift, extensions stay locked.