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

EXAMPLE

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

SEE ALSO

605       flatpak(1), flatpak-run(1), flatpak-override(1)
606

NOTES

608        1. freedesktop.org special directories
609           https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
610
611        2. freedesktop.org Base Directory Specification
612           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
613
614
615
616flatpak                                                    FLATPAK METADATA(5)
Impressum