Skip to main content

Testing a Flatpak from a release

Each Podman Desktop release includes a .flatpak bundle in the GitHub release assets. This page explains how to test that bundle correctly, including cases where sandbox permissions have changed between releases.

When you install Podman Desktop from Flathub, the permissions declared in io.podman_desktop.PodmanDesktop.yml are applied automatically. Installing a .flatpak bundle over an existing Flathub installation can leave an older cached permission profile active, causing failures such as lost filesystem access or silent D-Bus errors.

Prerequisites​

  • A Linux system with Flatpak installed.

  • The .flatpak bundle downloaded from the releases page.

  • (For building locally only) Flatpak builder, runtime, and SDK:

    $ flatpak remote-add --if-not-exists flathub --user https://flathub.org/repo/flathub.flatpakrepo
    $ flatpak install --user flathub org.flatpak.Builder org.freedesktop.Platform//25.08 org.freedesktop.Sdk//25.08

Procedure: Testing a release bundle​

  1. Uninstall any existing installation to remove stale cached permissions:

    $ flatpak uninstall --user io.podman_desktop.PodmanDesktop

    If Podman Desktop was installed system-wide, omit --user:

    $ flatpak uninstall io.podman_desktop.PodmanDesktop

  2. (Optional) Remove cached application data for a completely clean environment:

    $ rm -rf ~/.var/app/io.podman_desktop.PodmanDesktop
    caution

    This removes all local Podman Desktop settings and data stored under the Flatpak sandbox. Flatpak stores per-user app data in ~/.var/app/ for both user and system-wide installs. If multiple users have run Podman Desktop on the same machine, each user must run this command while logged in as themselves, or an administrator can clean another user's profile with sudo -u <username> rm -rf /home/<username>/.var/app/io.podman_desktop.PodmanDesktop.

  3. Install the downloaded bundle using the same scope as Step 1:

    For a user install:

    $ flatpak install --user ~/Downloads/podman-desktop-<version>.flatpak

    For a system-wide install, omit --user:

    $ flatpak install ~/Downloads/podman-desktop-<version>.flatpak

  4. Run Podman Desktop:

    For a user install:

    $ flatpak run io.podman_desktop.PodmanDesktop

    For a system-wide install, the command is the same:

    $ flatpak run io.podman_desktop.PodmanDesktop

  5. Verify the active permissions match the expected manifest:

    For a user install:

    $ flatpak info --user --show-permissions io.podman_desktop.PodmanDesktop

    For a system-wide install:

    $ flatpak info --show-permissions io.podman_desktop.PodmanDesktop

    Compare the output against the finish-args section of the upstream manifest.

Procedure: Building from the Flathub manifest​

When a pull request modifies Flatpak permissions, build the Flatpak locally from the updated manifest rather than relying on the pre-built release bundle.

  1. Clone the Flathub manifest repository:

    $ git clone https://github.com/flathub/io.podman_desktop.PodmanDesktop.git
    $ cd io.podman_desktop.PodmanDesktop

  2. Apply your changes to io.podman_desktop.PodmanDesktop.yml, for example, add or update finish-args entries.

  3. Build and install locally:

    $ flatpak run org.flatpak.Builder \
        --user \
        --install \
        --force-clean \
        build \
        io.podman_desktop.PodmanDesktop.yml

  4. Run Podman Desktop and verify the new permissions are in effect:

    $ flatpak run io.podman_desktop.PodmanDesktop

  5. Check the active permissions:

    $ flatpak info --user --show-permissions io.podman_desktop.PodmanDesktop

Reverting to the Flathub release​

To go back to the stable Flathub version after testing, run the commands that match the scope you used when installing:

For a user install:

$ flatpak uninstall --user io.podman_desktop.PodmanDesktop
$ flatpak install --user flathub io.podman_desktop.PodmanDesktop

For a system-wide install, omit --user:

$ flatpak uninstall io.podman_desktop.PodmanDesktop
$ flatpak install flathub io.podman_desktop.PodmanDesktop

Additional resources​

Next steps​