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)
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       tags (string list)
56           Tags to include in AppStream XML. Available since 0.4.12.
57
58   [Context]
59       This group determines various system resources that may be shared with
60       the application when it is run in a flatpak sandbox.
61
62       All keys in this group (and the group itself) are optional.
63
64       shared (list)
65           List of subsystems to share with the host system. Possible
66           subsystems: network, ipc. Available since 0.3.
67
68       sockets (list)
69           List of well-known sockets to make available in the sandbox.
70           Possible sockets: x11, wayland, fallback-x11, pulseaudio,
71           session-bus, system-bus, ssh-auth. When making a socket available,
72           flatpak also sets well-known environment variables like DISPLAY or
73           DBUS_SYSTEM_BUS_ADDRESS to let the application find sockets that
74           are not in a fixed location. Available since 0.3.
75
76       devices (list)
77           List of devices to make available in the sandbox. Possible values:
78
79           dri
80               Graphics direct rendering (/dev/dri). Available since 0.3.
81
82           kvm
83               Virtualization (/dev/kvm). Available since 0.6.12.
84
85           all
86               All device nodes in /dev. Available since 0.6.6.
87
88
89       filesystems (list)
90           List of filesystem subsets to make available to the application.
91           Possible values:
92
93           home
94               The entire home directory. Available since 0.3.
95
96           host
97               The entire host file system, except for directories that are
98               handled specially by Flatpak. In particular, this shares /home,
99               /media, /opt, /run/media and /srv if they exist.
100
101               /dev is not shared: use devices=all; instead.
102
103               Parts of /sys are always shared. This option does not make
104               additional files in /sys available.
105
106               These other reserved directories are currently excluded: /app,
107               /bin, /boot, /etc, /lib, /lib32, /lib64, /proc, /root, /run,
108               /sbin, /tmp, /usr, /var.
109
110               Available since 0.3.
111
112           xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
113           xdg-public-share, xdg-videos, xdg-templates
114               freedesktop.org special directories[1]. Available since 0.3.
115
116           xdg-desktop/path, xdg-documents/path, etc.
117               Subdirectories of freedesktop.org special directories.
118               Available since 0.4.13.
119
120           xdg-cache, xdg-config, xdg-data
121               Directories defined by the freedesktop.org Base Directory
122               Specification[2]. Available since 0.6.14.
123
124           xdg-cache/path, xdg-config/path, xdg-data/path
125               Subdirectories of directories defined by the freedesktop.org
126               Base Directory Specification. Available since 0.6.14.
127
128           xdg-run/path
129               Subdirectories of the XDG_RUNTIME_DIR defined by the
130               freedesktop.org Base Directory Specification[2]. Note that
131               xdg-run on its own is not supported. Available since 0.4.13.
132
133           /path
134               An arbitrary absolute path. Available since 0.3.
135
136           ~/path
137               An arbitrary path relative to the home directory. Available
138               since 0.3.
139
140           One of the above followed by :ro
141               Make the given directory available read-only.
142
143           One of the above followed by :rw
144               Make the given directory available read/write. This is the
145               default.
146
147           One of the above followed by :create
148               Make the given directory available read/write, and create it if
149               it does not already exist.
150
151
152       persistent (list)
153           List of homedir-relative paths to make available at the
154           corresponding path in the per-application home directory, allowing
155           the locations to be used for persistent data when the application
156           does not have access to the real homedir. For instance making
157           ".myapp" persistent would make "~/.myapp" in the sandbox a bind
158           mount to "~/.var/app/org.my.App/.myapp", thus allowing an
159           unmodified application to save data in the per-application
160           location. Available since 0.3.
161
162       features (list)
163           List of features available or unavailable to the application,
164           currently from the following list:
165
166           devel
167               Allow system calls used by development-oriented tools such as
168               perf, strace and gdb. Available since 0.6.10.
169
170           multiarch
171               Allow running multilib/multiarch binaries, for example i386
172               binaries in an x86_64 environment. Available since 0.6.12.
173
174           bluetooth
175               Allow the application to use bluetooth (AF_BLUETOOTH) sockets.
176               Note, for bluetooth to fully work you must also have network
177               access. Available since 0.11.8.
178
179           canbus
180               Allow the application to use canbus (AF_CAN) sockets. Note, for
181               this work you must also have network access. Available since
182               1.0.3.
183
184           A feature can be prefixed with !  to indicate the absence of that
185           feature, for example !devel if development and debugging are not
186           allowed.
187
188   [Instance]
189       This group only appears in /.flatpak-info for a running app, and not in
190       the metadata files written by application authors. It is filled in by
191       Flatpak itself.
192
193       instance-id (string)
194           The ID of the running instance. This number is used as the name of
195           the directory in XDG_RUNTIME_DIR/.flatpak where Flatpak stores
196           information about this instance.
197
198       instance-path (string)
199           The absolute path on the host system of the app's persistent
200           storage area in $HOME/.var.
201
202       app-path (string)
203           The absolute path on the host system of the app's app files, as
204           mounted at /app inside the container. Available since 0.6.10.
205
206       app-commit (string)
207           The commit ID or the application that is running.
208
209       app-extensions (list of strings)
210           A list of app extensions that are mounted into the running
211           instance. The format for each list item is EXTENSION_ID=COMMIT.
212
213       branch (string)
214           The branch of the app, for example stable. Available since 0.6.10.
215
216       arch (string)
217           The architecture of the running instance.
218
219       flatpak-version (string)
220           The version number of the Flatpak version that ran this app.
221           Available since 0.6.11.
222
223       runtime-path (string)
224           The absolute path on the host system of the app's runtime files, as
225           mounted at /usr inside the container. Available since 0.6.10.
226
227       runtime-commit (string)
228           The commit ID or the runtime that is used.
229
230       runtime-extensions (list of strings)
231           A list of runtime extensions that are mounted into the running
232           instance. The format for each list item is EXTENSION_ID=COMMIT.
233
234       extra-args (string)
235           Extra arguments that were passed to flatpak run.
236
237       sandbox (boolean)
238           Whether the --sandbox option was passed to flatpak run.
239
240       build (boolean)
241           Whether this instance was created by flatpak build.
242
243       session-bus-proxy (boolean)
244           True if this app cannot access the D-Bus session bus directly
245           (either it goes via a proxy, or it cannot access the session bus at
246           all). Available since 0.8.0.
247
248       system-bus-proxy (boolean)
249           True if this app cannot access the D-Bus system bus directly
250           (either it goes via a proxy, or it cannot access the system bus at
251           all). Available since 0.8.0.
252
253   [Session Bus Policy]
254       If the sockets key is not allowing full access to the D-Bus session
255       bus, then flatpak provides filtered access.
256
257       The default policy for the session bus only allows the application to
258       own its own application ID and subnames. For instance if the app is
259       called "org.my.App", it can only own "org.my.App" and "org.my.App.*".
260       Its also only allowed to talk to the bus itself (org.freedesktop.DBus)
261       and the portal APIs APIs (bus names of the form
262       org.freedesktop.portal.*).
263
264       Additionally the app is always allowed to reply to messages sent to it,
265       and emit broadcast signals (but these will not reach other sandboxed
266       apps unless they are allowed to talk to your app.
267
268       If the [Session Bus Policy] group is present, it provides policy for
269       session bus access.
270
271       Each key in this group has the form of a D-Bus bus name or prefix
272       thereof, for example org.gnome.SessionManager or
273       org.freedesktop.portal.*
274
275       The possible values for entry are, in increasing order or access:
276
277       none
278           The bus name or names in question is invisible to the application.
279           Available since 0.2.
280
281       see
282           The bus name or names can be enumerated by the application.
283           Available since 0.2.
284
285       talk
286           The application can send messages/ and receive replies and signals
287           from the bus name or names. Available since 0.2.
288
289       own
290           The application can own the bus name or names (as well as all the
291           above). Available since 0.2.
292
293   [System Bus Policy]
294       If the sockets key is not allowing full access to the D-Bus system bus,
295       then flatpak does not make the system bus available unless the [System
296       Bus Policy] group is present and provides a policy for filtered access.
297       Available since 0.2.
298
299       Entries in this group have the same form as for the [Session Bus
300       Policy] group. However, the app has no permissions by default.
301
302   [Environment]
303       The [Environment] group specifies environment variables to set when
304       running the application. Available since 0.3.
305
306       Entries in this group have the form VAR=VALUE where VAR is the name of
307       an environment variable to set.
308
309   [Extension NAME]
310       Runtimes and applications can define extension points, which allow
311       optional, additional runtimes to be mounted at a specified location
312       inside the sandbox when they are present on the system. Typical uses
313       for extension points include translations for applications, or
314       debuginfo for sdks. The name of the extension point is specified as
315       part of the group heading. Since 0.11.4, the name may optionally
316       include a tag in the NAME in the name@tag ref syntax if you wish to use
317       different configurations (eg, versions) of the same extension
318       concurrently. The "tag" is effectively ignored, but is necessary in
319       order to allow the same extension name to be specified more than once.
320
321       directory (string)
322           The relative path at which the extension will be mounted in the
323           sandbox. If the extension point is for an application, the path is
324           relative to /app, otherwise it is relative to /usr. This key is
325           mandatory. Available since 0.1.
326
327       version (string)
328           The branch to use when looking for the extension. If this is not
329           specified, it defaults to the branch of the application or runtime
330           that the extension point is for. Available since 0.4.1.
331
332       versions (string)
333           The branches to use when looking for the extension. If this is not
334           specified, it defaults to the branch of the application or runtime
335           that the extension point is for. Available since 0.9.1, and
336           backported to the 0.8.x branch in 0.8.4.
337
338       add-ld-path (string)
339           A path relative to the extension point directory that will be
340           appended to LD_LIBRARY_PATH. Available since 0.9.1, and backported
341           to the 0.8.x branch in 0.8.3.
342
343       merge-dirs (string)
344           A list of relative paths of directories below the extension point
345           directory that will be merged. Available since 0.9.1, and
346           backported to the 0.8.x branch in 0.8.3.
347
348       download-if (string)
349           A condition that must be true for the extension to be
350           auto-downloaded. The only currently recognized value is
351           active-gl-driver, which is true if the name of the active GL driver
352           matches the extension point basename. Available since 0.9.1, and
353           backported to the 0.8.x branch in 0.8.3.
354
355       autoprune-unless (string)
356           A condition that must be false for the extension to be considered
357           unused when pruning. For example, flatpak uninstall --unused uses
358           this information. The only currently recognized value is
359           active-gl-driver, which is true if the name of the active GL driver
360           matches the extension point basename. Available since 0.11.8.
361
362       enable-if (string)
363           A condition that must be true for the extension to be enabled. The
364           only currently recognized value is active-gl-driver, which is true
365           if the name of the active GL driver matches the extension point
366           basename. Available since 0.9.1, and backported to the 0.8.x branch
367           in 0.8.3.
368
369       subdirectory-suffix (string)
370           A suffix that gets appended to the directory name. This is very
371           useful when the extension point naming scheme is "reversed". For
372           example, an extension point for GTK+ themes would be
373           /usr/share/themes/$NAME/gtk-3.0, which could be achieved using
374           subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported
375           to the 0.8.x branch in 0.8.3.
376
377       subdirectories (boolean)
378           If this key is set to true, then flatpak will look for extensions
379           whose name is a prefix of the extension point name, and mount them
380           at the corresponding name below the subdirectory. Available since
381           0.1.
382
383       no-autodownload (boolean)
384           Whether to automatically download extensions matching this
385           extension point when updating or installing a 'related' application
386           or runtime. Available since 0.6.7.
387
388       locale-subset (boolean)
389           If set, then the extensions are partially downloaded by default,
390           based on the currently configured locales. This means that the
391           extension contents should be a set of directories with the language
392           code as name. Available since 0.9.13 (and 0.6.6 for any extensions
393           called *.Locale)
394
395       autodelete (boolean)
396           Whether to automatically delete extensions matching this extension
397           point when deleting a 'related' application or runtime. Available
398           since 0.6.7.
399
400       collection-id (string)
401           The ID of the collection that this extension point belongs to. If
402           this is unspecified, it defaults to the collection ID of the
403           application or runtime that the extension point is for. Currently,
404           extension points must be in the same collection as the application
405           or runtime that they are for. Available since 0.99.1.
406
407   [ExtensionOf]
408       This optional group may be present if the runtime is an extension.
409
410       ref (string)
411           The ref of the runtime or application that this extension belongs
412           to. Available since 0.9.1.
413
414       priority (integer)
415           The priority to give this extension when looking for the best
416           match. Default is 0. Available since 0.9.1, and backported to the
417           0.8.x branch in 0.8.3.
418
419       tag (string)
420           The tag name to use when searching for this extension's mount point
421           in the parent flatpak. Available since 0.11.4.
422
423   [Extra Data]
424       This optional group may be present if the runtime or application uses
425       extra data that gets downloaded separately. The data in this group gets
426       merged into the repository summary, with the xa.extra-data-sources key.
427
428       If multiple extra data sources are present, their uri, size and
429       checksum keys are grouped together by using the same suffix. If only
430       one extra data source is present, the suffix can be omitted.
431
432       NoRuntime (boolean)
433           Whether to mount the runtime while running the /app/bin/apply_extra
434           script. Defaults to true, i.e. not mounting the runtime. Available
435           since 0.9.1, and backported to the 0.8.x branch in 0.8.4.
436
437       uriX (string)
438           The uri for extra data source X. The only supported uri schemes are
439           http and https. Available since 0.6.13.
440
441       sizeX (integer)
442           The size for extra data source X. Available since 0.6.13.
443
444       checksumX (string)
445           The sha256 sum for extra data source X. Available since 0.6.13.
446
447   [Policy SUBSYSTEM]
448       Subsystems can define their own policies to be placed in a group whose
449       name has this form. Their values are treated as lists, in which items
450       can have their meaning negated by prepending ! to the value. They are
451       not otherwise parsed by Flatpak. Available since 0.6.13.
452

EXAMPLE

454           [Application]
455           name=org.gnome.Calculator
456           runtime=org.gnome.Platform/x86_64/3.20
457           sdk=org.gnome.Sdk/x86_64/3.20
458           command=gnome-calculator
459
460           [Context]
461           shared=network;ipc;
462           sockets=x11;wayland;
463           filesystems=xdg-run/dconf;~/.config/dconf:ro;
464
465           [Session Bus Policy]
466           ca.desrt.dconf=talk
467
468           [Environment]
469           DCONF_USER_CONFIG_DIR=.config/dconf
470
471           [Extension org.gnome.Calculator.Locale]
472           directory=share/runtime/locale
473           subdirectories=true
474
475           [Extension org.gnome.Calculator.Debug]
476           directory=lib/debug
477

SEE ALSO

479       flatpak(1), flatpak-run(1), flatpak-override(1)
480

NOTES

482        1. freedesktop.org special directories
483           https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
484
485        2. freedesktop.org Base Directory Specification
486           https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
487
488
489
490flatpak                                                    FLATPAK METADATA(5)
Impressum