Story / scenario opener
You installed Fedora Silverblue to get a stable, self-healing desktop. You open the terminal to grab a media player or a code editor. You type sudo dnf install vlc out of habit. The package manager refuses. It tells you the root filesystem is read-only. You are not on a traditional Fedora Workstation. You are on an immutable variant. The system will not let you drop random RPMs into /usr. That is by design. Your desktop applications need a different delivery mechanism. Flatpak is that mechanism. It runs outside the immutable base, keeps your system clean, and gives you the latest desktop software without touching the core OS.
What is actually happening
Silverblue mounts its root filesystem as a read-only rpm-ostree tree. Every package that ships with the OS is baked into a single atomic commit. When you boot, the system checks the commit hash. If it matches, the system runs. If you try to modify /usr or /bin, the kernel denies the write. This prevents dependency hell and broken upgrades. It also means traditional package managers cannot install user applications.
Flatpak solves this by using a separate directory tree. User installations live in ~/.local/share/flatpak. System-wide installations live in /var/lib/flatpak. The Flatpak runtime handles sandboxing, dependency resolution, and integration with the host desktop. When you install a Flatpak, it downloads the application bundle and any required runtimes. It creates a symlink in ~/.local/share/flatpak/exports/bin so the terminal can find the executable. The application runs in an isolated environment. It only sees the files and hardware you explicitly allow.
Think of the immutable base as a foundation. You cannot pour new concrete into it. Flatpak is a prefabricated module you place on top. You can swap modules, update them, or remove them without cracking the foundation. The system stays stable. Your apps stay current.
Flatpak also uses the Freedesktop portal system to bridge the sandbox and the host. Portals handle file pickers, screenshots, printing, and network access. They run as host-side services and communicate with sandboxed apps over D-Bus. This design keeps the application isolated while still providing desktop integration. You do not need to disable the sandbox to get basic functionality working. You only adjust permissions when an app legitimately needs broader access.
Installing and managing applications
Here is how to check whether Flathub is already configured as a remote repository. Flathub ships by default on Silverblue, but verifying it prevents silent failures later.
flatpak remotes
# Lists all configured remotes. Flathub should appear here.
# If it is missing, add it with: flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
# The --if-not-exists flag prevents duplicate entries that break updates.
Here is how to search for an application before you install it. Guessing the application ID often leads to installing the wrong package or pulling in outdated branches.
flatpak search vlc
# Queries Flathub for matching application IDs.
# Look for the official ID, usually org.videolan.VLC.
# Note the branch column. stable is the default target.
Here is how to install the application once you have the correct ID. The command pulls the app and its runtime if they are not already cached locally.
flatpak install flathub org.videolan.VLC
# Installs the app to your user directory by default.
# The --assumeyes flag can be added to skip the confirmation prompt.
# User installs are preferred on Silverblue to preserve system integrity.
Here is how to update every installed Flatpak application at once. Runtimes and applications update independently, so running this command regularly keeps your sandboxed software secure.
flatpak update
# Checks all configured remotes for newer commits.
# Downloads and applies updates for apps and runtimes.
# Run this weekly alongside your rpm-ostree updates.
Here is how to remove an application and clean up unused runtimes. Leaving orphaned runtimes consumes disk space unnecessarily.
flatpak uninstall org.videolan.VLC
# Removes the application from your user directory.
# Add --delete-only to remove only the app but keep the runtime.
# Run flatpak uninstall --unused afterward to reclaim space.
Reboot before you debug. Half the time the symptom is gone.
Verifying the installation
Here is how to confirm the application is registered and ready to run. The list command shows the installation directory, branch, and origin.
flatpak list
# Displays all installed Flatpak applications and runtimes.
# Check the Installation column. user means it lives in your home directory.
# system means it lives in /var/lib/flatpak and requires root.
Here is how to verify the executable symlink exists in your user path. Flatpak does not modify /usr/bin. It relies on your shell to find the wrapper script.
ls -l ~/.local/share/flatpak/exports/bin/
# Shows symlinks pointing to the flatpak wrapper.
# The wrapper handles sandbox setup before launching the actual binary.
# If the symlink is missing, log out and back in to refresh your PATH.
Here is how to check disk usage across your Flatpak installations. Runtimes can grow quickly if you install apps from multiple desktop environments.
du -sh ~/.local/share/flatpak/
# Reports the total size of your user Flatpak directory.
# Large sizes usually indicate multiple GNOME or KDE runtimes.
# Remove unused runtimes with flatpak uninstall --unused to free space.
Run the application from the terminal once to catch immediate sandbox errors. The first launch often prints permission warnings or missing portal messages.
Common pitfalls and what the error looks like
Flatpak sandboxing blocks access to the host filesystem by default. Applications cannot read your home directory unless you grant explicit permission. You will see a permission denied message when an app tries to open a file outside its sandbox.
Error: Permission denied: Cannot access file '/home/user/Documents/report.pdf'
The error means the application lacks filesystem access. You can grant access using the override command. Be careful. Granting --filesystem=host removes the sandbox boundary entirely. Use specific paths instead.
flatpak override --filesystem=~/Documents org.videolan.VLC
# Grants read-write access to your Documents folder only.
# The override persists across updates and reboots.
# Check current overrides with: flatpak override --show org.videolan.VLC
Another common issue is missing runtimes. Flatpak applications depend on a base runtime like org.gnome.Platform or org.kde.Platform. If the runtime is not installed, the application fails to launch.
Error: No matches for runtime org.gnome.Platform//45
The error means your system lacks the required runtime version. Install it manually before retrying the application installation.
flatpak install flathub runtime org.gnome.Platform//45
# Downloads the GNOME runtime without an application.
//45 specifies the exact branch version.
# Runtimes are shared across multiple applications.
Configuration drift happens when you try to reset an application state. Flatpak stores user data in ~/.var/app/<app-id>. If an app crashes or misbehaves, clearing this directory forces a fresh start.
flatpak reset org.videolan.VLC
# Resets the application configuration to defaults.
# Does not delete downloaded media or library databases.
# Use rm -rf ~/.var/app/org.videolan.VLC for a complete wipe.
Check the journal for portal failures. Flatpak uses Freedesktop portals for file pickers, screenshots, and network access. Portal errors show up in the system log.
journalctl -xeu flatpak-session-helper.service
# Shows real-time logs for the Flatpak session helper.
# Look for portal negotiation failures or D-Bus errors.
# Restart the helper with systemctl --user restart flatpak-session-helper.service if it hangs.
Trust the package manager. Manual file edits drift, snapshots stay.
When to use this vs alternatives
Use Flatpak when you need desktop applications that update independently of the OS. Use rpm-ostree install when you need a system package that integrates deeply with the host, such as a custom kernel module or a low-level utility. Use dnf when you are running Fedora Workstation and want traditional RPM management. Stay on user-level Flatpak installs when you want to avoid sudo and keep your home directory portable across machines. Use system-wide Flatpak installs only when you manage a shared workstation and need applications available to every user account. Use flatpak override when an application legitimately requires host access that the sandbox blocks. Use flatpak reset when configuration corruption causes crashes or missing UI elements. Use rpm-ostree upgrade when you need to update the immutable base system itself.