1FLATPAK METADATA(5)            flatpak metadata            FLATPAK METADATA(5)
2
3
4

NAME

6       flatpak-metadata - Information about an application or runtime
7

DESCRIPTION

9       Flatpak uses metadata files to describe applications and runtimes. The
10       metadata file for a deployed application or runtime is placed in the
11       toplevel deploy directory. For example, the metadata for the locally
12       installed application org.gnome.Calculator is in
13       ~/.local/share/flatpak/app/org.gnome.Calculator/current/active/metadata.
14
15       Most aspects of the metadata configuration can be overridden when
16       launching applications, either temporarily via options of the flatpak
17       run command, or permanently with the flatpak override command.
18
19       A metadata file describing the effective configuration is available
20       inside the running sandbox at /.flatpak-info. For compatibility with
21       older Flatpak versions, /run/user/$UID/flatpak-info is a symbolic link
22       to the same file.
23

FILE FORMAT

25       The metadata file is using the same .ini file format that is used for
26       systemd unit files or application .desktop files.
27
28   [Application] or [Runtime]
29       Metadata for applications starts with an [Application] group, metadata
30       for runtimes with a [Runtime] group.
31
32       The following keys can be present in these groups:
33
34       name (string)
35           The name of the application or runtime. This key is mandatory.
36
37       runtime (string)
38           The fully qualified name of the runtime that is used by the
39           application. This key is mandatory for applications.
40
41       sdk (string)
42           The fully qualified name of the sdk that matches the runtime.
43           Available since 0.1.
44
45       command (string)
46           The command to run. Only relevant for applications. Available since
47           0.1.
48
49       required-flatpak (string list)
50           The required version of Flatpak to run this application or runtime.
51           For applications, this was available since 0.8.0. For runtimes,
52           this was available since 0.9.1, and backported to 0.8.3 for the
53           0.8.x branch.
54
55           Flatpak after version 1.4.3 and 1.2.5 support multiple versions
56           here. This can be useful if you need to support features that are
57           backported to a previous stable series. For example if you want to
58           use a feature added in 1.6.0 that was also backported to 1.4.4 you
59           would use 1.6.0;1.4.4;. Note that older versions of flatpak will
60           just use the first element in the list, so make that the largest
61           version.
62
63       tags (string list)
64           Tags to include in AppStream XML. Typical values in use on Flathub
65           include beta, stable, proprietary and upstream-maintained.
66           Available since 0.4.12.
67
68   [Context]
69       This group determines various system resources that may be shared with
70       the application when it is run in a flatpak sandbox.
71
72       All keys in this group (and the group itself) are optional.
73
74       shared (list)
75           List of subsystems to share with the host system. Possible
76           subsystems: network, ipc. Available since 0.3.
77
78       sockets (list)
79           List of well-known sockets to make available in the sandbox.
80           Possible sockets: x11, wayland, fallback-x11, pulseaudio,
81           session-bus, system-bus, ssh-auth, pcsc, cups. When making a socket
82           available, flatpak also sets well-known environment variables like
83           DISPLAY or DBUS_SYSTEM_BUS_ADDRESS to let the application find
84           sockets that are not in a fixed location. Available since 0.3.
85
86       devices (list)
87           List of devices to make available in the sandbox. Possible values:
88
89           dri
90               Graphics direct rendering (/dev/dri). Available since 0.3.
91
92           input
93               Input devices (/dev/input).
94
95           kvm
96               Virtualization (/dev/kvm). Available since 0.6.12.
97
98           all
99               All device nodes in /dev, but not /dev/shm (which is separately
100               specified). Available since 0.6.6.
101
102           shm
103               Access to the host /dev/shm (/dev/shm). Available since 1.6.1.
104
105
106       filesystems (list)
107           List of filesystem subsets to make available to the application.
108           Possible values:
109
110           home
111               The entire home directory. Available since 0.3.
112
113           home/path
114               Alias for ~/path Available since 1.10. For better compatibility
115               with older Flatpak versions, prefer to write this as ~/path.
116
117           host
118               The entire host file system, except for directories that are
119               handled specially by Flatpak. In particular, this shares /home,
120               /media, /opt, /run/media and /srv if they exist.
121
122               /dev is not shared: use devices=all; instead.
123
124               Parts of /sys are always shared. This option does not make
125               additional files in /sys available.
126
127               Additionally, this keyword provides all of the same directories
128               in /run/host as the host-os and host-etc keywords. If this
129               keyword is used in conjunction with one of the host- keywords,
130               whichever access level is higher (more permissive) will be used
131               for the directories in /run/host: for example,
132               host:rw;host-os:ro; is equivalent to host:rw;.
133
134               These other reserved directories are currently excluded: /app,
135               /bin, /boot, /efi, /etc, /lib, /lib32, /lib64, /proc, /root,
136               /run, /sbin, /tmp, /usr, /var.
137
138               Available since 0.3.
139
140           host-os
141               The host operating system's libraries, executables and static
142               data from /usr and the related directories /bin, /lib, /lib32,
143               /lib64, /sbin. Additionally, this keyword provides access to a
144               subset of /etc that is associated with packaged libraries and
145               executables, even if the host-etc keyword was not used:
146               /etc/ld.so.cache, (used by the dynamic linker) and
147               /etc/alternatives (on operating systems that use it, such as
148               Debian).
149
150               To avoid conflicting with the Flatpak runtime, these are
151               mounted in the sandbox at /run/host/usr,
152               /run/host/etc/ld.so.cache and so on.
153
154               Available since 1.7.
155
156           host-etc
157               The host operating system's configuration from /etc.
158
159               To avoid conflicting with the Flatpak runtime, this is mounted
160               in the sandbox at /run/host/etc.
161
162               Available since 1.7.
163
164           xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
165           xdg-public-share, xdg-videos, xdg-templates
166               freedesktop.org special directories[1]. Available since 0.3.
167
168           xdg-desktop/path, xdg-documents/path, etc.
169               Subdirectories of freedesktop.org special directories.
170               Available since 0.4.13.
171
172           xdg-cache, xdg-config, xdg-data
173               Directories defined by the freedesktop.org Base Directory
174               Specification[2]. Available since 0.6.14.
175
176           xdg-cache/path, xdg-config/path, xdg-data/path
177               Subdirectories of directories defined by the freedesktop.org
178               Base Directory Specification. Available since 0.6.14.
179
180           xdg-run/path
181               Subdirectories of the XDG_RUNTIME_DIR defined by the
182               freedesktop.org Base Directory Specification. Note that xdg-run
183               on its own is not supported. Available since 0.4.13.
184
185           /path
186               An arbitrary absolute path. Available since 0.3.
187
188           ~/path
189               An arbitrary path relative to the home directory. Available
190               since 0.3.
191
192           ~
193               The same as home. Available since 1.10. For better
194               compatibility with older Flatpak versions, prefer to write this
195               as home.
196
197           One of the above followed by :ro
198               Make the given directory available read-only.
199
200           One of the above followed by :rw
201               Make the given directory available read/write. This is the
202               default.
203
204           One of the above followed by :create
205               Make the given directory available read/write, and create it if
206               it does not already exist.
207
208
209       persistent (list)
210           List of homedir-relative paths to make available at the
211           corresponding path in the per-application home directory, allowing
212           the locations to be used for persistent data when the application
213           does not have access to the real homedir. For instance making
214           ".myapp" persistent would make "~/.myapp" in the sandbox a bind
215           mount to "~/.var/app/org.my.App/.myapp", thus allowing an
216           unmodified application to save data in the per-application
217           location. Available since 0.3.
218
219       features (list)
220           List of features available or unavailable to the application,
221           currently from the following list:
222
223           devel
224               Allow system calls used by development-oriented tools such as
225               perf, strace and gdb. Available since 0.6.10.
226
227           multiarch
228               Allow running multilib/multiarch binaries, for example i386
229               binaries in an x86_64 environment. Available since 0.6.12.
230
231           bluetooth
232               Allow the application to use bluetooth (AF_BLUETOOTH) sockets.
233               Note, for bluetooth to fully work you must also have network
234               access. Available since 0.11.8.
235
236           canbus
237               Allow the application to use canbus (AF_CAN) sockets. Note, for
238               this work you must also have network access. Available since
239               1.0.3.
240
241           per-app-dev-shm
242               Share a single instance of /dev/shm between all instances of
243               this application run by the same user ID, including
244               sub-sandboxes. If the application has the shm device permission
245               in its devices list, then this feature flag is ignored.
246               Available since 1.12.0.
247
248           A feature can be prefixed with !  to indicate the absence of that
249           feature, for example !devel if development and debugging are not
250           allowed.
251
252       unset-environment (list)
253           A list of names of environment variables to unset. Note that
254           environment variables to set to a value (possibly empty) appear in
255           the [Environment] group instead.
256
257   [Instance]
258       This group only appears in /.flatpak-info for a running app, and not in
259       the metadata files written by application authors. It is filled in by
260       Flatpak itself.
261
262       instance-id (string)
263           The ID of the running instance. This number is used as the name of
264           the directory in XDG_RUNTIME_DIR/.flatpak where Flatpak stores
265           information about this instance.
266
267       instance-path (string)
268           The absolute path on the host system of the app's persistent
269           storage area in $HOME/.var.
270
271       app-path (string)
272           The absolute path on the host system of the app's app files, as
273           mounted at /app inside the container. Available since 0.6.10.
274           Since 1.12.0, if flatpak run was run with the --app-path option,
275           this key gives the absolute path of whatever files were mounted on
276           /app, even if that differs from the app's normal app files.  If
277           flatpak run was run with --app-path= (resulting in an empty
278           directory being mounted on /app), the value is set to the empty
279           string.
280
281       original-app-path (string)
282           If flatpak run was run with the --app-path option, this key gives
283           the absolute path of the app's original files, as mounted at
284           /run/parent/app inside the container. Available since 1.12.0.  If
285           this key is missing, the app files are given by app-path.
286
287       app-commit (string)
288           The commit ID of the application that is running. The filename of a
289           deployment of this commit can be found in original-app-path if
290           present, or app-path otherwise.
291
292       app-extensions (list of strings)
293           A list of app extensions that are mounted into the running
294           instance. The format for each list item is EXTENSION_ID=COMMIT. If
295           original-app-path is present, the extensions are mounted below
296           /run/parent/app; otherwise, they are mounted below /app.
297
298       branch (string)
299           The branch of the app, for example stable. Available since 0.6.10.
300
301       arch (string)
302           The architecture of the running instance.
303
304       flatpak-version (string)
305           The version number of the Flatpak version that ran this app.
306           Available since 0.6.11.
307
308       runtime-path (string)
309           The absolute path on the host system of the app's runtime files, as
310           mounted at /usr inside the container. Available since 0.6.10.
311           Since 1.12.0, if flatpak run was run with the --usr-path option,
312           this key gives the absolute path of whatever files were mounted on
313           /usr, even if that differs from the app's normal runtime files.
314
315       original-runtime-path (string)
316           If flatpak run was run with the --runtime-path option, this key
317           gives the absolute path of the app's original runtime, as mounted
318           at /run/parent/usr inside the container. Available since 1.12.0.
319           If this key is missing, the runtime files are given by
320           runtime-path.
321
322       runtime-commit (string)
323           The commit ID of the runtime that is used. The filename of a
324           deployment of this commit can be found in original-runtime-path if
325           present, or runtime-path otherwise.
326
327       runtime-extensions (list of strings)
328           A list of runtime extensions that are mounted into the running
329           instance. The format for each list item is EXTENSION_ID=COMMIT. If
330           original-app-path is present, the extensions are mounted below
331           /run/parent/usr; otherwise, they are mounted below /usr.
332
333       extra-args (string)
334           Extra arguments that were passed to flatpak run.
335
336       sandbox (boolean)
337           Whether the --sandbox option was passed to flatpak run.
338
339       build (boolean)
340           Whether this instance was created by flatpak build.
341
342       session-bus-proxy (boolean)
343           True if this app cannot access the D-Bus session bus directly
344           (either it goes via a proxy, or it cannot access the session bus at
345           all). Available since 0.8.0.
346
347       system-bus-proxy (boolean)
348           True if this app cannot access the D-Bus system bus directly
349           (either it goes via a proxy, or it cannot access the system bus at
350           all). Available since 0.8.0.
351
352   [Session Bus Policy]
353       If the sockets key is not allowing full access to the D-Bus session
354       bus, then flatpak provides filtered access.
355
356       The default policy for the session bus only allows the application to
357       own its own application ID, its subnames and its own application id as
358       a subname of "org.mpris.MediaPlayer2". For instance if the app is
359       called "org.my.App", it can only own "org.my.App", "org.my.App.*" and
360       "org.mpris.MediaPlayer2.org.my.App". It is only allowed to talk to
361       names matching those patterns, plus the bus itself
362       (org.freedesktop.DBus) and the portal APIs (bus names of the form
363       org.freedesktop.portal.*).
364
365       Additionally the app is always allowed to reply to messages sent to it,
366       and emit broadcast signals (but these will not reach other sandboxed
367       apps unless they are allowed to talk to your app.
368
369       If the [Session Bus Policy] group is present, it provides policy for
370       session bus access.
371
372       Each key in this group has the form of a D-Bus bus name or prefix
373       thereof, for example org.gnome.SessionManager or
374       org.freedesktop.portal.*
375
376       The possible values for entry are, in increasing order or access:
377
378       none
379           The bus name or names in question is invisible to the application.
380           Available since 0.2.
381
382       see
383           The bus name or names can be enumerated by the application.
384           Available since 0.2.
385
386       talk
387           The application can send messages/ and receive replies and signals
388           from the bus name or names. Available since 0.2.
389
390       own
391           The application can own the bus name or names (as well as all the
392           above). Available since 0.2.
393
394   [System Bus Policy]
395       If the sockets key is not allowing full access to the D-Bus system bus,
396       then flatpak does not make the system bus available unless the [System
397       Bus Policy] group is present and provides a policy for filtered access.
398       Available since 0.2.
399
400       Entries in this group have the same form as for the [Session Bus
401       Policy] group. However, the app has no permissions by default.
402
403   [Environment]
404       The [Environment] group specifies environment variables to set when
405       running the application. Available since 0.3.
406
407       Entries in this group have the form VAR=VALUE where VAR is the name of
408       an environment variable to set.
409
410       Note that environment variables can also be unset (removed from the
411       environment) by listing them in the unset-environment entry of the
412       [Context] group.
413
414   [Extension NAME]
415       Runtimes and applications can define extension points, which allow
416       optional, additional runtimes to be mounted at a specified location
417       inside the sandbox when they are present on the system. Typical uses
418       for extension points include translations for applications, or
419       debuginfo for sdks. The name of the extension point is specified as
420       part of the group heading. Since 0.11.4, the name may optionally
421       include a tag in the NAME in the name@tag ref syntax if you wish to use
422       different configurations (eg, versions) of the same extension
423       concurrently. The "tag" is effectively ignored, but is necessary in
424       order to allow the same extension name to be specified more than once.
425
426       directory (string)
427           The relative path at which the extension will be mounted in the
428           sandbox. If the extension point is for an application, the path is
429           relative to /app, otherwise it is relative to /usr. This key is
430           mandatory. Available since 0.1.
431
432       version (string)
433           The branch to use when looking for the extension. If this is not
434           specified, it defaults to the branch of the application or runtime
435           that the extension point is for. Available since 0.4.1.
436
437       versions (string)
438           The branches to use when looking for the extension. If this is not
439           specified, it defaults to the branch of the application or runtime
440           that the extension point is for. Available since 0.9.1, and
441           backported to the 0.8.x branch in 0.8.4.
442
443       add-ld-path (string)
444           A path relative to the extension point directory that will be
445           appended to LD_LIBRARY_PATH. Available since 0.9.1, and backported
446           to the 0.8.x branch in 0.8.3.
447
448       merge-dirs (string)
449           A list of relative paths of directories below the extension point
450           directory that will be merged. Available since 0.9.1, and
451           backported to the 0.8.x branch in 0.8.3.
452
453       download-if (string)
454           A condition that must be true for the extension to be
455           auto-downloaded. As of 1.1.1 this supports multiple conditions
456           separated by semi-colons.
457
458           These are the supported conditions:
459
460           active-gl-driver
461               Is true if the name of the active GL driver matches the
462               extension point basename. Available since 0.9.1, and backported
463               to the 0.8.x branch in 0.8.3.
464
465           active-gtk-theme
466               Is true if the name of the current GTK theme (via
467               org.gnome.desktop.interface GSetting) matches the extension
468               point basename. Added 0.10.1.
469
470           have-intel-gpu
471               Is true if the i915 kernel module is loaded. Added 0.10.1.
472
473           have-kernel-module-*
474               Is true if the suffix (case-sensitive) is found in
475               /proc/modules. For example have-kernel-module-nvidia. Added
476               1.13.1.
477
478           on-xdg-desktop-*
479               Is true if the suffix (case-insensitively) is in the
480               XDG_CURRENT_DESKTOP env var. For example
481               on-xdg-desktop-GNOME-classic. Added 1.1.1.
482
483       autoprune-unless (string)
484           A condition that must be false for the extension to be considered
485           unused when pruning. For example, flatpak uninstall --unused uses
486           this information. The only currently recognized value is
487           active-gl-driver, which is true if the name of the active GL driver
488           matches the extension point basename. Available since 0.11.8.
489
490       enable-if (string)
491           A condition that must be true for the extension to be enabled. As
492           of 1.1.1 this supports multiple conditions separated by
493           semi-colons. See download-if for available conditions.
494
495       subdirectory-suffix (string)
496           A suffix that gets appended to the directory name. This is very
497           useful when the extension point naming scheme is "reversed". For
498           example, an extension point for GTK+ themes would be
499           /usr/share/themes/$NAME/gtk-3.0, which could be achieved using
500           subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported
501           to the 0.8.x branch in 0.8.3.
502
503       subdirectories (boolean)
504           If this key is set to true, then flatpak will look for extensions
505           whose name is a prefix of the extension point name, and mount them
506           at the corresponding name below the subdirectory. Available since
507           0.1.
508
509       no-autodownload (boolean)
510           Whether to automatically download extensions matching this
511           extension point when updating or installing a 'related' application
512           or runtime. Available since 0.6.7.
513
514       locale-subset (boolean)
515           If set, then the extensions are partially downloaded by default,
516           based on the currently configured locales. This means that the
517           extension contents should be a set of directories with the language
518           code as name. Available since 0.9.13 (and 0.6.6 for any extensions
519           called *.Locale)
520
521       autodelete (boolean)
522           Whether to automatically delete extensions matching this extension
523           point when deleting a 'related' application or runtime. Available
524           since 0.6.7.
525
526       collection-id (string)
527           The ID of the collection that this extension point belongs to. If
528           this is unspecified, it defaults to the collection ID of the
529           application or runtime that the extension point is for. Currently,
530           extension points must be in the same collection as the application
531           or runtime that they are for. Available since 0.99.1.
532
533   [ExtensionOf]
534       This optional group may be present if the runtime is an extension.
535
536       ref (string)
537           The ref of the runtime or application that this extension belongs
538           to. Available since 0.9.1.
539
540       runtime (string)
541           The runtime this extension will be inside of. If it is an app
542           extension, this is the app's runtime; otherwise, this is identical
543           to ref, without the runtime/ prefix. Available since 1.5.0.
544
545       priority (integer)
546           The priority to give this extension when looking for the best
547           match. Default is 0. Available since 0.9.1, and backported to the
548           0.8.x branch in 0.8.3.
549
550       tag (string)
551           The tag name to use when searching for this extension's mount point
552           in the parent flatpak. Available since 0.11.4.
553
554   [Extra Data]
555       This optional group may be present if the runtime or application uses
556       extra data that gets downloaded separately. The data in this group gets
557       merged into the repository summary, with the xa.extra-data-sources key.
558
559       If multiple extra data sources are present, their uri, size and
560       checksum keys are grouped together by using the same suffix. If only
561       one extra data source is present, the suffix can be omitted.
562
563       NoRuntime (boolean)
564           Whether to mount the runtime while running the /app/bin/apply_extra
565           script. Defaults to true, i.e. not mounting the runtime. Available
566           since 0.9.1, and backported to the 0.8.x branch in 0.8.4.
567
568       uriX (string)
569           The uri for extra data source X. The only supported uri schemes are
570           http and https. Available since 0.6.13.
571
572       sizeX (integer)
573           The size for extra data source X. Available since 0.6.13.
574
575       checksumX (string)
576           The sha256 sum for extra data source X. Available since 0.6.13.
577
578   [Policy SUBSYSTEM]
579       Subsystems can define their own policies to be placed in a group whose
580       name has this form. Their values are treated as lists, in which items
581       can have their meaning negated by prepending ! to the value. They are
582       not otherwise parsed by Flatpak. Available since 0.6.13.
583

EXAMPLE

585           [Application]
586           name=org.gnome.Calculator
587           runtime=org.gnome.Platform/x86_64/3.20
588           sdk=org.gnome.Sdk/x86_64/3.20
589           command=gnome-calculator
590
591           [Context]
592           shared=network;ipc;
593           sockets=x11;wayland;
594           filesystems=xdg-run/dconf;~/.config/dconf:ro;
595
596           [Session Bus Policy]
597           ca.desrt.dconf=talk
598
599           [Environment]
600           DCONF_USER_CONFIG_DIR=.config/dconf
601
602           [Extension org.gnome.Calculator.Locale]
603           directory=share/runtime/locale
604           subdirectories=true
605
606           [Extension org.gnome.Calculator.Debug]
607           directory=lib/debug
608

SEE ALSO

610       flatpak(1), flatpak-run(1), flatpak-override(1)
611

NOTES

613        1. freedesktop.org special directories
614           https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
615
616        2. freedesktop.org Base Directory Specification
617           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
618
619
620
621flatpak                                                    FLATPAK METADATA(5)
Impressum