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 kvm
93 Virtualization (/dev/kvm). Available since 0.6.12.
94 all
96 All device nodes in /dev, but not /dev/shm (which is separately
97 specified). Available since 0.6.6.
98 shm
100 Access to the host /dev/shm (/dev/shm). Available since 1.6.1.
101 filesystems (list)
104 List of filesystem subsets to make available to the application.
105 Possible values:
106 home
108 The entire home directory. Available since 0.3.
109 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 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 /dev is not shared: use devices=all; instead.
120 Parts of /sys are always shared. This option does not make
122 additional files in /sys available.
123 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 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 Available since 0.3.
136 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 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 Available since 1.7.
152 host-etc
154 The host operating system's configuration from /etc.
155 To avoid conflicting with the Flatpak runtime, this is mounted
157 in the sandbox at /run/host/etc.
158 Available since 1.7.
160 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 xdg-desktop/path, xdg-documents/path, etc.
166 Subdirectories of freedesktop.org special directories.
167 Available since 0.4.13.
168 xdg-cache, xdg-config, xdg-data
170 Directories defined by the freedesktop.org Base Directory
171 Specification[2]. Available since 0.6.14.
172 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 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 /path
183 An arbitrary absolute path. Available since 0.3.
184 ~/path
186 An arbitrary path relative to the home directory. Available
187 since 0.3.
188 ~
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 One of the above followed by :ro
195 Make the given directory available read-only.
196 One of the above followed by :rw
198 Make the given directory available read/write. This is the
199 default.
200 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 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 features (list)
217 List of features available or unavailable to the application,
218 currently from the following list:
219 devel
221 Allow system calls used by development-oriented tools such as
222 perf, strace and gdb. Available since 0.6.10.
223 multiarch
225 Allow running multilib/multiarch binaries, for example i386
226 binaries in an x86_64 environment. Available since 0.6.12.
227 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 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 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 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 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 [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 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 instance-path (string)
265 The absolute path on the host system of the app's persistent
266 storage area in $HOME/.var.
267 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 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 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 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 branch (string)
296 The branch of the app, for example stable. Available since 0.6.10.
297 arch (string)
299 The architecture of the running instance.
300 flatpak-version (string)
302 The version number of the Flatpak version that ran this app.
303 Available since 0.6.11.
304 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 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 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 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 extra-args (string)
331 Extra arguments that were passed to flatpak run.
332 sandbox (boolean)
334 Whether the --sandbox option was passed to flatpak run.
335 build (boolean)
337 Whether this instance was created by flatpak build.
338 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 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 [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 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 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 If the [Session Bus Policy] group is present, it provides policy for
365 session bus access.
366 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 The possible values for entry are, in increasing order or access:
372 none
374 The bus name or names in question is invisible to the application.
375 Available since 0.2.
376 see
378 The bus name or names can be enumerated by the application.
379 Available since 0.2.
380 talk
382 The application can send messages/ and receive replies and signals
383 from the bus name or names. Available since 0.2.
384 own
386 The application can own the bus name or names (as well as all the
387 above). Available since 0.2.
388 [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 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 [Environment]
399 The [Environment] group specifies environment variables to set when
400 running the application. Available since 0.3.
401 Entries in this group have the form VAR=VALUE where VAR is the name of
403 an environment variable to set.
404 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 [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 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 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 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 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 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 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 These are the supported conditions:
454 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 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 have-intel-gpu
466 Is true if the i915 kernel module is loaded. Added 0.10.1.
467 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 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 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 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 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 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 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 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 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 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 [ExtensionOf]
529 This optional group may be present if the runtime is an extension.
530 ref (string)
532 The ref of the runtime or application that this extension belongs
533 to. Available since 0.9.1.
534 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 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 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 [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 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 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 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 sizeX (integer)
568 The size for extra data source X. Available since 0.6.13.
569 checksumX (string)
571 The sha256 sum for extra data source X. Available since 0.6.13.
572 [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
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 [Context]
587 shared=network;ipc;
588 sockets=x11;wayland;
589 filesystems=xdg-run/dconf;~/.config/dconf:ro;
590 [Session Bus Policy]
592 ca.desrt.dconf=talk
593 [Environment]
595 DCONF_USER_CONFIG_DIR=.config/dconf
596 [Extension org.gnome.Calculator.Locale]
598 directory=share/runtime/locale
599 subdirectories=true
600 [Extension org.gnome.Calculator.Debug]
602 directory=lib/debug
603
605 flatpak(1), flatpak-run(1), flatpak-override(1)
606
608 1. freedesktop.org special directories
609 https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
610 2. freedesktop.org Base Directory Specification
612 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
613flatpak FLATPAK METADATA(5)