This section includes documentation on how to debug Flatpak apps.
Running debugging tools¶
Because Flatpak runs each application inside a sandbox, debugging tools
can’t be used in the usual way, and must instead be run from inside the
sandbox. To get a shell inside an application’s sandbox, it can be run with
$ flatpak run --command=sh --devel <application-id>
This creates a sandbox for the application with the given ID and, instead
of running the application, runs a shell inside the sandbox. From the shell
prompt, it is then possible to run the application. This can also be done
using any debugging tools that you want to use. For example, to run the
$ gdb /app/bin/<application-binary>
This works because the
--devel option tells Flatpak to use the SDK as the
runtime, which includes debugging tools like
also adjusts the sandbox setup to enable debugging.
The Freedesktop SDK (on which many others are based), includes a range
of debugging tools, such as
dconf, and many others.
gdb is much more useful when it has access to debug information for the
application and the runtime it is using. Flatpak splits this information off
into debug extensions, which you should install before debugging an
$ flatpak install <runtime-id>.Debug
--devel option is used, Flatpak will automatically use any
matching debug extensions that it finds.
It is also possible to get a shell inside an application sandbox without having
to install it. This is done using
$ flatpak-builder --run <build-dir> <manifest> sh
This sets up a sandbox that is populated with the build results found in the build directory, and runs a shell inside it.
Creating a .Debug extension¶
Like many other packaging systems, Flatpak separates bulky debug information
from regular content and ships it separately, in what is called a
When an application is built,
.Debug extension. This can be disabled with the
Overriding sandbox permissions¶
It is sometimes useful to have extra permissions in a sandbox when debugging. This can be achieved using the various sandbox options that are accepted by the run command. For example:
$ flatpak run --devel --command=sh --system-talk-name=org.freedesktop.login1 <application-id>
This command runs a shell in the sandbox for the given application, granting it system bus access to the bus name owned by logind.
Inspecting portal permissions¶
Flatpak has a number of commands that allow to manage portal permissions for applications.
To see all portal permissions of an application, use:
$ flatpak permission-show <application-id>
To reset all portal permissions of an application, use:
$ flatpak permission-reset <application-id>
Interacting with running sandboxes¶
You can see all the apps that are currently running in Flatpak sandboxes (since 1.2):
$ flatpak ps
And, if you need to, you can terminate one by force (since 1.2):
$ flatpak kill <application-id>