1FLATPAK METADATA(5) flatpak metadata FLATPAK METADATA(5)
2
6 flatpak-metadata - Information about an application or runtime
7
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 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 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
25 The metadata file is using the same .ini file format that is used for
26 systemd unit files or application .desktop files.
27 [Application] or [Runtime]
29 Metadata for applications starts with an [Application] group, metadata
30 for runtimes with a [Runtime] group.
31 The following keys can be present in these groups:
33 name (string)
35 The name of the application or runtime. This key is mandatory.
36 runtime (string)
38 The fully qualified name of the runtime that is used by the
39 application. This key is mandatory for applications.
40 sdk (string)
42 The fully qualified name of the sdk that matches the runtime.
43 Available since 0.1.
44 command (string)
46 The command to run. Only relevant for applications. Available since
47 0.1.
48 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 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 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 [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 All keys in this group (and the group itself) are optional.
73 shared (list)
75 List of subsystems to share with the host system. Possible
76 subsystems: network, ipc. Available since 0.3.
77 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 devices (list)
87 List of devices to make available in the sandbox. Possible values:
88 dri
90 Graphics direct rendering (/dev/dri). Available since 0.3.
91 input
93 Input devices (/dev/input).
94 kvm
96 Virtualization (/dev/kvm). Available since 0.6.12.
97 all
99 All device nodes in /dev, but not /dev/shm (which is separately
100 specified). Available since 0.6.6.
101 shm
103 Access to the host /dev/shm (/dev/shm). Available since 1.6.1.
104 filesystems (list)
107 List of filesystem subsets to make available to the application.
108 Possible values:
109 home
111 The entire home directory. Available since 0.3.
112 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 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 /dev is not shared: use devices=all; instead.
123 Parts of /sys are always shared. This option does not make
125 additional files in /sys available.
126 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 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 Available since 0.3.
139 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 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 Available since 1.7.
155 host-etc
157 The host operating system's configuration from /etc.
158 To avoid conflicting with the Flatpak runtime, this is mounted
160 in the sandbox at /run/host/etc.
161 Available since 1.7.
163 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 xdg-desktop/path, xdg-documents/path, etc.
169 Subdirectories of freedesktop.org special directories.
170 Available since 0.4.13.
171 xdg-cache, xdg-config, xdg-data
173 Directories defined by the freedesktop.org Base Directory
174 Specification[2]. Available since 0.6.14.
175 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 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 /path
186 An arbitrary absolute path. Available since 0.3.
187 ~/path
189 An arbitrary path relative to the home directory. Available
190 since 0.3.
191 ~
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 One of the above followed by :ro
198 Make the given directory available read-only.
199 One of the above followed by :rw
201 Make the given directory available read/write. This is the
202 default.
203 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 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 features (list)
220 List of features available or unavailable to the application,
221 currently from the following list:
222 devel
224 Allow system calls used by development-oriented tools such as
225 perf, strace and gdb. Available since 0.6.10.
226 multiarch
228 Allow running multilib/multiarch binaries, for example i386
229 binaries in an x86_64 environment. Available since 0.6.12.
230 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 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 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 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 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 [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 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 instance-path (string)
268 The absolute path on the host system of the app's persistent
269 storage area in $HOME/.var.
270 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 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 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 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 branch (string)
299 The branch of the app, for example stable. Available since 0.6.10.
300 arch (string)
302 The architecture of the running instance.
303 flatpak-version (string)
305 The version number of the Flatpak version that ran this app.
306 Available since 0.6.11.
307 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 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 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 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 extra-args (string)
334 Extra arguments that were passed to flatpak run.
335 sandbox (boolean)
337 Whether the --sandbox option was passed to flatpak run.
338 build (boolean)
340 Whether this instance was created by flatpak build.
341 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 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 [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 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 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 If the [Session Bus Policy] group is present, it provides policy for
370 session bus access.
371 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 The possible values for entry are, in increasing order or access:
377 none
379 The bus name or names in question is invisible to the application.
380 Available since 0.2.
381 see
383 The bus name or names can be enumerated by the application.
384 Available since 0.2.
385 talk
387 The application can send messages/ and receive replies and signals
388 from the bus name or names. Available since 0.2.
389 own
391 The application can own the bus name or names (as well as all the
392 above). Available since 0.2.
393 [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 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 [Environment]
404 The [Environment] group specifies environment variables to set when
405 running the application. Available since 0.3.
406 Entries in this group have the form VAR=VALUE where VAR is the name of
408 an environment variable to set.
409 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 [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 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 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 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 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 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 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 These are the supported conditions:
459 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 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 have-intel-gpu
471 Is true if the i915 kernel module is loaded. Added 0.10.1.
472 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 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 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 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 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 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 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 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 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 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 [ExtensionOf]
534 This optional group may be present if the runtime is an extension.
535 ref (string)
537 The ref of the runtime or application that this extension belongs
538 to. Available since 0.9.1.
539 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 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 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 [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 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 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 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 sizeX (integer)
573 The size for extra data source X. Available since 0.6.13.
574 checksumX (string)
576 The sha256 sum for extra data source X. Available since 0.6.13.
577 [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
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 [Context]
592 shared=network;ipc;
593 sockets=x11;wayland;
594 filesystems=xdg-run/dconf;~/.config/dconf:ro;
595 [Session Bus Policy]
597 ca.desrt.dconf=talk
598 [Environment]
600 DCONF_USER_CONFIG_DIR=.config/dconf
601 [Extension org.gnome.Calculator.Locale]
603 directory=share/runtime/locale
604 subdirectories=true
605 [Extension org.gnome.Calculator.Debug]
607 directory=lib/debug
608
610 flatpak(1), flatpak-run(1), flatpak-override(1)
611
613 1. freedesktop.org special directories
614 https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
615 2. freedesktop.org Base Directory Specification
617 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
618flatpak FLATPAK METADATA(5)