Using Flatpak - Flatpak documentation
Skip to content
Flatpak documentation
Introduction to Flatpak
Getting Started
Building
Debugging
Publishing
Desktop Integration
Flatpak as a developer platform
Tips and Tricks
Reference Documentation
Flatpak Command Reference
Flatpak Builder Command Reference
Available Runtimes
Under the Hood
libflatpak API Reference
Portal API Reference
View this page
Edit this page
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.
Applications can be found in any of your remotes using the
command. For example:
$ flatpak search gimp
Search will return any applications matching the search terms. Each search
result includes the application ID and the remote that the application is
in. In this example, the search term is
gimp
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
On this page
Using Flatpak
The flatpak command
Identifiers
Identifier triples
System versus user
Basic commands
List remotes
Add a remote
Remove a remote
Install applications
Running applications
Updating
List installed applications
Remove an application
Troubleshooting