Flatpak: Difference between revisions

Latest revision as of 15:22, 25 May 2025

Flatpak is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributions.

Prerequisites

Enable community repository.
Enable D-Bus, specifically D-Bus session needs to be started separately for each user.
Enable Polkit.
Install xdg-desktop-portal package along with an implementation of xdg-desktop-portal, e.g. xdg-desktop-portal-gtk package.

Installation

Following instructions are based on official Flatpak guide with additional customisations.

Install Flatpak

Install flatpak package using the command:

# apk add flatpak

Install the flatpak plugin for software managers

Install the Flatpak plugin Software for either the GNOME Software (since v3.13) or KDE Discover (since v3.11), making it possible to install apps without needing the command line.

To install, for GNOME Software run:

# apk add gnome-software-plugin-flatpak

For KDE Discover run:

# apk add discover-backend-flatpak

Add the Flathub repository

Next you need to add a repository, for this guide we will use the recommended repository, Flathub.

$ flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo

Flatpak is now ready to use immediately, however flatpak desktop entries will not appear until you restart your desktop session by logging out and then logging back in.

Now all you have to do is install apps!

Flatpak usage

To get all of the available options to use with the flatpak command run: flatpak --help or flatpak -h

Search for flatpak apps

To search for applications run flatpak --user search <appplicationname>

Example:

~$ flatpak --user search chromium Name Description Application ID Version Branch Remotes Chromium Web Browser The web browser from Chromium project org.chromium.Chromium 96.0.4664.93 stable flathub Chromium B.S.U. Fast paced, arcade-style, top-scrolling space shooter net.sourceforge.chromium-bsu 0.9.16.1 stable flathub ungoogled-chromium A lightweight approach to removing Google web service dependency com.github.Eloston.UngoogledChromium 96.0.4664.45 stable flathub

Install flatpak apps

When installing a flatpak app, a number of questions regarding what permissions the app requires and what runtimes or other software it needs will be asked.

To install a package run flatpak --user install <applicationname>

~$ flatpak --user install com.github.Eloston.UngoogledChromium Looking for matches… com.github.Eloston.UngoogledChromium permissions: ipc network cups pulseaudio wayland x11 devices file access [1] dbus access [2] bus ownership [3] system dbus access [4] [1] /run/.heim_org.h5l.kcm-socket, home, xdg-run/pipewire-0 [2] org.freedesktop.FileManager1, org.freedesktop.Notifications, org.freedesktop.secrets, org.gnome.SessionManager [3] org.mpris.MediaPlayer2.chromium.* [4] org.freedesktop.Avahi, org.freedesktop.UPower ID Branch Op Remote Download 1. com.github.Eloston.UngoogledChromium.Codecs stable i flathub < 1.1 MB 2. com.github.Eloston.UngoogledChromium.Locale stable i flathub < 112.8 kB 3. com.github.Eloston.UngoogledChromium stable i flathub < 119.0 MB Proceed with these changes to the system installation? [Y/n]:

or if you don't know or don't want to type the exact package name:

~$ flatpak --user install chromium Looking for matches… Similar refs found for ‘chromium’ in remote ‘flathub’ (system): 1) app/net.sourceforge.chromium-bsu/x86_64/stable 2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable 3) runtime/org.chromium.Chromium.Codecs/x86_64/stable 4) app/org.chromium.Chromium/x86_64/stable 5) app/com.github.Eloston.UngoogledChromium/x86_64/stable Which do you want to use (0 to abort)? [0-5]:

Remove flatpak apps

To remove a package run: flatpak --user remove <applicationname>

~$ flatpak --user remove com.github.Eloston.UngoogledChromium ID Branch Op 1. com.github.Eloston.UngoogledChromium stable r 2. com.github.Eloston.UngoogledChromium.Codecs stable r 3. com.github.Eloston.UngoogledChromium.Locale stable r Proceed with these changes to the system installation? [Y/n]:

or if you don't know or don't want to type the exact package name:

~$ flatpak --user remove chromium Similar installed refs found for ‘chromium’: 1) app/com.github.Eloston.UngoogledChromium/x86_64/stable (system) 2) runtime/com.github.Eloston.UngoogledChromium.Codecs/x86_64/stable (system) 3) All of the above Which do you want to use (0 to abort)? [0-3]:

Troubleshooting

This material is work-in-progress ...

More documentation and testing is needed, but everything currently here should be safe to follow.
(Last edited by Prabuanand on 25 May 2025.)

Permission errors

If you receive errors about permissions then you may need to add your user to the flatpak group.

Note: You need to log out and log back in or reboot for the group change(s) to take effect

Application launch errors

If the application is not starting try running it with

flatpak run the.application.name

on a terminal. If this yields an a dbus error starting with Failed to connect to session bus then you might solve this by adding

export $(dbus-launch)

in /etc/profile.

Fixing audio issues

Make sure that XDG_RUNTIME_DIR is properly configured and re-login if necessary.

When you launch a Flatpak you will need to start pulseaudio as well:

$ pulseaudio --start && flatpak run com.example.Example

Unable to upload files

If you are unable to upload files from the host, this maybe due to Flatpak sandbox and you may have to manually add the authorization.

This can be done with the following commands:

$ flatpak override ApplicationID --filesystem=/home/user/Downloads

Where ApplicationID is given by:

$ flatpak list

For example:

$ flatpak override org.signal.Signal --filesystem=/home/user/Downloads

Error while opening repository

There is a current issue where sometimes flatpak will try to read the system-wide repository even if your install is with --user. This will result in failure to launch a flatpak application with the terminal reading ""error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory". An alpine user has posted more information, as well as a workaround, at https://github.com/flatpak/flatpak/issues/5488

@@ Line 1: / Line 1: @@
-{{Draft|More documentation and testing is needed, but everything currently here should be safe to follow.}}
+[https://flatpak.org/ Flatpak] is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributions.
-Flatpak is a technology for building and distributing applications with the goal of having a universal package format for all Linux distributons, it is similar to [https://en.wikipedia.org/wiki/Snappy_(package_manager) Snap],
+== Prerequisites ==
+* [[Repositories#Managing_repositories|Enable]] community repository.
+* Enable [[D-Bus]], specifically [[D-Bus#D-Bus session|D-Bus session]] needs to be started separately for each user.
+* Enable [[Polkit]].
+* Install {{Pkg|xdg-desktop-portal}} package along with an implementation of {{ic|xdg-desktop-portal}}, e.g. {{Pkg|xdg-desktop-portal-gtk}} package.
-= Setup / Installation =
+== Installation ==
-''From: https://flatpak.org/setup/Alpine/''
+Following instructions are based on [https://flathub.org/setup/Alpine official Flatpak guide] with additional customisations.
-To install Flatpak you will need to enable the  Community repository, See: [https://wiki.alpinelinux.org/wiki/Post_installation#Repositories Post Installation - Repositories]
+=== Install Flatpak ===
-To install Flatpak run:
+Install {{Pkg|flatpak}} package using the command: {{cmd|# apk add {{Pkg|flatpak}}}}
-{{cmd|# apk add flatpak}}
+=== Install the flatpak plugin for software managers ===
-It's recommended to run flatpak as your user, rather than as root. Therefore, add your user to the flatpak group:
+Install the Flatpak plugin Software for either the GNOME Software (since v3.13) or KDE Discover (since v3.11), making it possible to install apps without needing the command line.
+:To install, for GNOME Software run:{{cmd|# apk add gnome-software-plugin-flatpak}}
+:For KDE Discover run:{{cmd|# apk add discover-backend-flatpak}}
-{{cmd|# adduser <YourUsername> flatpak}}
+=== Add the Flathub repository ===
-Next you need to add a repository, for this guide we will use the recommended repository, [https://flathub.org Flathub].
+Next you need to add a repository, for this guide we will use the recommended repository, [https://flathub.org Flathub]. {{cmd|$ flatpak remote-add --user --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo}}
-{{cmd|flatpak remote-add --user --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo}}
+Flatpak is now ready to use immediately, however flatpak desktop entries will not appear until you restart your desktop session by logging out and then logging back in.
-Now reboot to complete setup
+Now all you have to do is install apps!
-{{Note|graphical installation of Flatpak apps may not be possible with Alpine.}}
+== Flatpak usage ==
-<br>
+To get all of the available options to use with the '''flatpak''' command run: '''flatpak --help''' or '''flatpak -h'''
-= Usage =
+=== Search for flatpak apps ===
-To get all of the available options to use with the '''flatpak''' command run: '''flatpak --help''' or '''flatpak -h''',
+To search for applications run '''flatpak --user search <appplicationname>'''
-<br>
+Example:
-==== Search ====
-To search for applications run '''flatpak search <appplicationname>'''
+<p style="background-color:#f9f9f9; border:1px dashed #2f6fab; line-height:1.1em; padding:1em; font-family:monospace; font-size:10pt; white-space:pre; overflow:auto;"><span style="color:green;">~</span>'''$''' flatpak --user search chromium
-Example:
+Name                   Description                                                        Application ID                        Version       Branch  Remotes
-{{cat|flatpak search chromium|Name                   Description                                                        Application ID                        Version       Branch  Remotes
 Chromium Web Browser   The web browser from Chromium project                              org.chromium.Chromium                 96.0.4664.93  stable  flathub
 Chromium B.S.U.        Fast paced, arcade-style, top-scrolling space shooter              net.sourceforge.chromium-bsu          0.9.16.1      stable  flathub
-ungoogled-chromium     A lightweight approach to removing Google web service dependency   com.github.Eloston.UngoogledChromium  96.0.4664.45  stable  flathub}}
+ungoogled-chromium     A lightweight approach to removing Google web service dependency   com.github.Eloston.UngoogledChromium  96.0.4664.45  stable  flathub
+</p>
-<br>
+=== Install flatpak apps ===
-==== Install ====
+When installing a flatpak app, a number of questions regarding what permissions the app requires and what runtimes or other software it needs will be asked.
-To install a package run '''flatpak install <applicationname>'''
+To install a package run '''flatpak --user install <applicationname>'''
-{{cat|$ flatpak install com.github.Eloston.UngoogledChromium|Looking for matches…
+<p style="background-color:#f9f9f9; border:1px dashed #2f6fab; line-height:1.1em; padding:1em; font-family:monospace; font-size:10pt; white-space:pre; overflow:auto;"><span style="color:green;">~</span>'''$''' flatpak --user install com.github.Eloston.UngoogledChromium
+Looking for matches…
 com.github.Eloston.UngoogledChromium permissions:
@@ Line 67: / Line 73: @@
 .     com.github.Eloston.UngoogledChromium                    stable             i             flathub            < 119.0 MB
-Proceed with these changes to the system installation? [Y/n]:}}
+Proceed with these changes to the system installation? [Y/n]:
+</p>
+or if you don't know or don't want to type the exact package name:
-or if you dont know or dont want to type the exact package name:
+<p style="background-color:#f9f9f9; border:1px dashed #2f6fab; line-height:1.1em; padding:1em; font-family:monospace; font-size:10pt; white-space:pre; overflow:auto;"><span style="color:green;">~</span>'''$''' flatpak --user install chromium
-{{cat|$ flatpak install chromium|Looking for matches…
+Looking for matches…
 Similar refs found for ‘chromium’ in remote ‘flathub’ (system):
@@ Line 80: / Line 89: @@
 ) app/com.github.Eloston.UngoogledChromium/x86_64/stable
-Which do you want to use (0 to abort)? [0-5]:}}
+Which do you want to use (0 to abort)? [0-5]:
+</p>
-<br>
-==== Remove ====
+=== Remove flatpak apps ===
-To remove a package run: '''flatpak remove <applicationname>'''
+To remove a package run: '''flatpak --user remove <applicationname>'''
-{{cat|$ flatpak remove com.github.Eloston.UngoogledChromium|
+<p style="background-color:#f9f9f9; border:1px dashed #2f6fab; line-height:1.1em; padding:1em; font-family:monospace; font-size:10pt; white-space:pre; overflow:auto;"><span style="color:green;">~</span>'''$''' flatpak --user remove com.github.Eloston.UngoogledChromium
          ID                                                     Branch           Op
@@ Line 95: / Line 103: @@
 .     com.github.Eloston.UngoogledChromium.Locale            stable           r
-Proceed with these changes to the system installation? [Y/n]:}}
+Proceed with these changes to the system installation? [Y/n]:
+</p>
+or if you don't know or don't want to type the exact package name:
-or if you dont know or dont want to type the exact package name:
+<p style="background-color:#f9f9f9; border:1px dashed #2f6fab; line-height:1.1em; padding:1em; font-family:monospace; font-size:10pt; white-space:pre; overflow:auto;"><span style="color:green;">~</span>'''$''' flatpak --user remove chromium
-{{cat|$ flatpak remove chromium|Similar installed refs found for ‘chromium’:
+Similar installed refs found for ‘chromium’:
 ) app/com.github.Eloston.UngoogledChromium/x86_64/stable (system)
@@ Line 105: / Line 117: @@
 ) All of the above
-Which do you want to use (0 to abort)? [0-3]:}}
+Which do you want to use (0 to abort)? [0-3]:
+</p>
+== Troubleshooting ==
+{{Draft|More documentation and testing is needed, but everything currently here should be safe to follow.}}
+=== Permission errors ===
+If you receive errors about permissions then you may need to add your user to the '''flatpak''' group.
+{{Note|You need to log out and log back in or reboot for the group change(s) to take effect}}
+=== Application launch errors ===
-<br>
+If the application is not starting try running it with {{Cmd|<nowiki>flatpak run the.application.name</nowiki>}} on a terminal. If this yields an a dbus error starting with ''Failed to connect to session bus'' then you might solve this by adding
-= Developers =
+{{Cmd|<nowiki>export $(dbus-launch)</nowiki>}}
-* [https://docs.flatpak.org/en/latest/available-runtimes.html Flatpak - available runtimes]
+in {{Path|/etc/profile}}.
+=== Fixing audio issues ===
-These are all hosted on [https://flathub.org/ Flathub.org].
+Make sure that [[XDG_RUNTIME_DIR]] is properly configured and re-login if necessary.
-= Troubleshooting =
+When you launch a Flatpak you will need to start pulseaudio as well:
-==== Permission errors ====
+{{Cmd|$ pulseaudio --start && flatpak run com.example.Example}}
-If you receive errors about permissions then you may need to add your user to the '''flatpak''' group:
+=== Unable to upload files ===
-{{cmd|adduser <YourUsername> flatpak}}
+If you are unable to upload files from the host, this maybe due to [https://docs.flatpak.org/en/latest/sandbox-permissions.html Flatpak sandbox] and you may have to manually add the authorization.
-<br>
+This can be done with the following commands:
-{{Note|You may need to log out and log back in or reboot for the group change(s) to take effect}}
+{{Cmd|<nowiki>$ flatpak override ApplicationID --filesystem=/home/user/Downloads</nowiki>}}
+Where ''ApplicationID'' is given by:
-<br>
+{{Cmd|$ flatpak list}}
-==== Fixing audio issues ====
+For example:
-If you have a minimal setup and don't have access to audio devices you will need to set the XDG_RUNTIME_DIR variable. Save the following script in /etc/profile.d/xdg_runtime_dir.sh and re-login to have it set up properly.
+{{Cmd|<nowiki>$ flatpak override org.signal.Signal --filesystem=/home/user/Downloads</nowiki>}}
- if test -z "${XDG_RUNTIME_DIR}"; then
+=== Error while opening repository ===
-   export XDG_RUNTIME_DIR=/tmp/$(id -u)
- fi
-When you launch a Flatpak you will need to start pulseaudio as well:
+There is a current issue where sometimes flatpak will try to read the system-wide repository even if your install is with --user. This will result in failure to launch a flatpak application with the terminal reading ""error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory". An alpine user has posted more information, as well as a workaround, at https://github.com/flatpak/flatpak/issues/5488
-{{Cmd|pulseaudio --start && flatpak run com.example.Example}}
-<br>
+== See also ==
-= Links =
+* [https://flatpak.org/setup/Alpine/ Official setup Guide]
+* [https://docs.flatpak.org/en/latest/available-runtimes.html Flatpak - available runtimes]
 * [https://flatpak.org/ Flatpak]
 * [https://flathub.org/ Flathub]
 * [https://winepak.github.io/ Winepak]
-<br>
-= See Also =
 [[Category:Package Manager]]
-[[Category: Desktop]]