Using Flatpak#

This page provides an introduction to the flatpak command line interface, and explains essential technical conventions as well as the most common commands.

End users shouldn’t generally need to use this page or the Flatpak command line interface, since Flatpak can be easily used through graphical software management tools, though they are of course free to use the command line if they prefer!

The flatpak command#

flatpak is the primary Flatpak command, to which specific commands are appended. For example, the command to install something is flatpak install and the command to uninstall is flatpak uninstall.

Identifiers#

Flatpak identifies each application and runtime using a unique three-part identifier, such as com.company.App. The final segment of this address is the object’s name, and the preceding part identifies the developer, so that the same developer can have multiple applications, like com.company.App1 and com.company.App2.

Identifier triples#

Typically it is sufficient to refer to objects using their ID. However, in some situations it is necessary to refer to a specific version of an object, or to a specific architecture. For example, some applications might be available as a stable and a testing version, in which case it is necessary to specify which one you want to install.

Flatpak allows architectures and versions to be specified using an object’s identifier triple. This takes the form of name/architecture/branch, such as com.company.App/i386/stable. (Branch is the term used to refer to versions of the same object.) The first part of the triple is the ID, the second part is the architecture, and the third part is the branch.

Identifier triples can also be used to specify just the architecture or the branch, by leaving part of the triple blank. For example, com.company.App//stable would just specify the branch, and com.company.App/i386// just specifies the architecture.

The Flatpak CLI provides feedback if the architecture or branch of an object needs to be specified.

System versus user#

Flatpak commands can be run either system-wide or per-user. Applications and runtimes that are installed system-wide are available to all users on the system. Applications and runtimes that are installed per-user are only available to the users that installed them.

The same principle applies to repositories - repositories that have been added system-wide are available to all users, whereas per-user repositories can only be used by a particular user.

Flatpak commands are run system-wide by default. If you are installing applications for day-to-day usage, it is recommended to stick with this default behavior.

However, running commands per-user can be useful for testing and development purposes, since objects that are installed in this way won’t be available to other users on the system. To do this, use the --user option, which can be used in combination with most flatpak commands.

Commands behave in exactly the same way if they are run per-user rather than system-wide.

Basic commands#

This section covers basic commands needed to install, run and manage Flatpak applications. For the full list of Flatpak commands, run flatpak --help or see the Flatpak Command Reference.

List remotes#

To list the remotes that you have configured on your system, run:

$ flatpak remotes

This gives a list of the existing remotes that have been added. The list indicates whether each remote has been added per-user or system-wide.

Add a remote#

The most convenient way to add a remote is by using a .flatpakrepo file, which includes both the details of the remote and its GPG key:

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

Here, flathub is the local name that is given to the remote. The URL points to the remote’s .flatpakrepo file. --if-not-exists stops the command from producing an error if the remote already exists.

Remove a remote#

To remove a remote, run:

$ flatpak remote-delete flathub

In this case, flathub is the remote’s local name.

Install applications#

To install an application, run:

$ flatpak install flathub org.gimp.GIMP

Here, flathub is the name of the remote the application is to be installed from, and org.gimp.GIMP is the ID of the application.

Sometimes, an application will require a particular runtime, and this will be installed prior to the application.

The details of the application to be installed can also be provided by a .flatpakref file, which can be either remote or local. To specify a .flatpakref instead of manually providing the remote and application ID, run:

$ flatpak install https://flathub.org/repo/appstream/org.gimp.GIMP.flatpakref

If the .flatpakref file specifies that the application is to be installed from a remote that hasn’t already been added, you will be asked whether to add it before the application is installed.

Since Flatpak 1.2, the install command can search for applications. A simple:

$ flatpak install gimp

will confirm the remote and application and proceed to install.

Running applications#

Once an application has been installed, it can be launched using the run command and its application ID:

$ flatpak run org.gimp.GIMP

Updating#

To update all your installed applications and runtimes to the latest version, run:

$ flatpak update

List installed applications#

To list the applications and runtimes you have installed, run:

$ flatpak list

Alternatively, to just list installed applications, run:

$ flatpak list --app

Remove an application#

To remove an application, run:

$ flatpak uninstall org.gimp.GIMP

Troubleshooting#

Flatpak has a few commands that can help you to get things working again when something goes wrong.

To remove runtimes and extensions that are not used by installed applications, use:

$ flatpak uninstall --unused

To fix inconsistencies with your local installation, use:

$ flatpak repair

Flatpak also has a number of commands to manage the portal permissions of installed apps. To reset all portal permissions for an app, use flatpak permission-reset:

$ flatpak permission-reset org.gimp.GIMP

To find out what changes have been made to your Flatpak installation over time, you can take a look at the logs (since 1.2):

$ flatpak history