Freedesktop quick reference¶
In order to ensure interoperability, flatpak adheres strictly to a number of freedesktop standards and practices. This page describes the basic conventions that should be followed when building a flatpak app.
Application icons can be in either png or svg format, must use the
application’s appid as a prefix and be placed in
If interested, you can read the full spec here
Desktop files are used by desktop environments in order to identify and display available applications to the user, they contain information about how to launch the application, its icon and categories among others.
A minimal desktop file needs at least the application’s Name, Exec command, Type and Icon:
[Desktop Entry] Name=Gnome Dictionary Exec=gnome-dictionary --database=dictionary.db Type=Application Icon=org.gnome.Dictionary
Your desktop file should be prefixed with your application’s appid and
/app/share/applications/ within your app.
It’s recommended to use
desktop-file-validate to check your file
for errors before including it.
A special note about the
Exec line: When installing an app, Flatpak will
automatically rewrite the included
.desktop file so that the app will be
started through Flatpak. The rewritten desktop file is then exported to a path
exports/share/applications/org.gnome.Dictionary.desktop under your
Flatpak installation directory (usually
~/.local/share/flatpak/). In the case of
Exec line looks like this:
Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=gnome-dictionary org.gnome.Dictionary --database=dictionary.db
The command from the original desktop file will be part of the
--command argument to Flatpak and arguments will be passed through.
This means that in most cases, it should match the value of the
command: line in your app’s manifest.
If you want the
--command argument to be omitted from the
run command in the generated desktop file, you can leave the
value in the source desktop file empty:
[Desktop Entry] Name=Gnome Dictionary Exec= Type=Application Icon=org.gnome.Dictionary
This way, the generated
Exec line looks like this:
Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 org.gnome.Dictionary
With Flatpak ≤ 1.12.7, a warning may be shown when exporting a build with an empty Exec= line to a repository:
(flatpak build-export:189863): GLib-CRITICAL **: 22:15:27.398: g_path_is_absolute: assertion 'file_name != NULL' failed
This warning can be ignored.
You can find more general information about desktop files here. If interested, you can read also the full spec here.
Appdata files are used by application stores (e.g. KDE Discover, GNOME Software) in order to display metadata about your application, such as a description, screenshots, changelogs when updates are available, and other miscellaneous things.
Your Appdata file should be prefixed with your application’s appid and
/app/share/metainfo/. You should also use
appstream-util validate-relax to check your file for errors before
If interested, you can read the full spec here.