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, /etc, /lib, /lib32, /lib64, /proc, /root, /run,
133 /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 A feature can be prefixed with ! to indicate the absence of that
239 feature, for example !devel if development and debugging are not
240 allowed.
241 unset-environment (list)
243 A list of names of environment variables to unset. Note that
244 environment variables to set to a value (possibly empty) appear in
245 the [Environment] group instead.
246 [Instance]
248 This group only appears in /.flatpak-info for a running app, and not in
249 the metadata files written by application authors. It is filled in by
250 Flatpak itself.
251 instance-id (string)
253 The ID of the running instance. This number is used as the name of
254 the directory in XDG_RUNTIME_DIR/.flatpak where Flatpak stores
255 information about this instance.
256 instance-path (string)
258 The absolute path on the host system of the app's persistent
259 storage area in $HOME/.var.
260 app-path (string)
262 The absolute path on the host system of the app's app files, as
263 mounted at /app inside the container. Available since 0.6.10.
264 app-commit (string)
266 The commit ID of the application that is running.
267 app-extensions (list of strings)
269 A list of app extensions that are mounted into the running
270 instance. The format for each list item is EXTENSION_ID=COMMIT.
271 branch (string)
273 The branch of the app, for example stable. Available since 0.6.10.
274 arch (string)
276 The architecture of the running instance.
277 flatpak-version (string)
279 The version number of the Flatpak version that ran this app.
280 Available since 0.6.11.
281 runtime-path (string)
283 The absolute path on the host system of the app's runtime files, as
284 mounted at /usr inside the container. Available since 0.6.10.
285 runtime-commit (string)
287 The commit ID of the runtime that is used.
288 runtime-extensions (list of strings)
290 A list of runtime extensions that are mounted into the running
291 instance. The format for each list item is EXTENSION_ID=COMMIT.
292 extra-args (string)
294 Extra arguments that were passed to flatpak run.
295 sandbox (boolean)
297 Whether the --sandbox option was passed to flatpak run.
298 build (boolean)
300 Whether this instance was created by flatpak build.
301 session-bus-proxy (boolean)
303 True if this app cannot access the D-Bus session bus directly
304 (either it goes via a proxy, or it cannot access the session bus at
305 all). Available since 0.8.0.
306 system-bus-proxy (boolean)
308 True if this app cannot access the D-Bus system bus directly
309 (either it goes via a proxy, or it cannot access the system bus at
310 all). Available since 0.8.0.
311 [Session Bus Policy]
313 If the sockets key is not allowing full access to the D-Bus session
314 bus, then flatpak provides filtered access.
315 The default policy for the session bus only allows the application to
317 own its own application ID and subnames. For instance if the app is
318 called "org.my.App", it can only own "org.my.App" and "org.my.App.*".
319 Its also only allowed to talk to the bus itself (org.freedesktop.DBus)
320 and the portal APIs APIs (bus names of the form
321 org.freedesktop.portal.*).
322 Additionally the app is always allowed to reply to messages sent to it,
324 and emit broadcast signals (but these will not reach other sandboxed
325 apps unless they are allowed to talk to your app.
326 If the [Session Bus Policy] group is present, it provides policy for
328 session bus access.
329 Each key in this group has the form of a D-Bus bus name or prefix
331 thereof, for example org.gnome.SessionManager or
332 org.freedesktop.portal.*
333 The possible values for entry are, in increasing order or access:
335 none
337 The bus name or names in question is invisible to the application.
338 Available since 0.2.
339 see
341 The bus name or names can be enumerated by the application.
342 Available since 0.2.
343 talk
345 The application can send messages/ and receive replies and signals
346 from the bus name or names. Available since 0.2.
347 own
349 The application can own the bus name or names (as well as all the
350 above). Available since 0.2.
351 [System Bus Policy]
353 If the sockets key is not allowing full access to the D-Bus system bus,
354 then flatpak does not make the system bus available unless the [System
355 Bus Policy] group is present and provides a policy for filtered access.
356 Available since 0.2.
357 Entries in this group have the same form as for the [Session Bus
359 Policy] group. However, the app has no permissions by default.
360 [Environment]
362 The [Environment] group specifies environment variables to set when
363 running the application. Available since 0.3.
364 Entries in this group have the form VAR=VALUE where VAR is the name of
366 an environment variable to set.
367 Note that environment variables can also be unset (removed from the
369 environment) by listing them in the unset-environment entry of the
370 [Context] group.
371 [Extension NAME]
373 Runtimes and applications can define extension points, which allow
374 optional, additional runtimes to be mounted at a specified location
375 inside the sandbox when they are present on the system. Typical uses
376 for extension points include translations for applications, or
377 debuginfo for sdks. The name of the extension point is specified as
378 part of the group heading. Since 0.11.4, the name may optionally
379 include a tag in the NAME in the name@tag ref syntax if you wish to use
380 different configurations (eg, versions) of the same extension
381 concurrently. The "tag" is effectively ignored, but is necessary in
382 order to allow the same extension name to be specified more than once.
383 directory (string)
385 The relative path at which the extension will be mounted in the
386 sandbox. If the extension point is for an application, the path is
387 relative to /app, otherwise it is relative to /usr. This key is
388 mandatory. Available since 0.1.
389 version (string)
391 The branch to use when looking for the extension. If this is not
392 specified, it defaults to the branch of the application or runtime
393 that the extension point is for. Available since 0.4.1.
394 versions (string)
396 The branches to use when looking for the extension. If this is not
397 specified, it defaults to the branch of the application or runtime
398 that the extension point is for. Available since 0.9.1, and
399 backported to the 0.8.x branch in 0.8.4.
400 add-ld-path (string)
402 A path relative to the extension point directory that will be
403 appended to LD_LIBRARY_PATH. Available since 0.9.1, and backported
404 to the 0.8.x branch in 0.8.3.
405 merge-dirs (string)
407 A list of relative paths of directories below the extension point
408 directory that will be merged. Available since 0.9.1, and
409 backported to the 0.8.x branch in 0.8.3.
410 download-if (string)
412 A condition that must be true for the extension to be
413 auto-downloaded. As of 1.1.1 this supports multiple conditions
414 separated by semi-colons.
415 These are the supported conditions:
417 active-gl-driver
419 Is true if the name of the active GL driver matches the
420 extension point basename. Available since 0.9.1, and backported
421 to the 0.8.x branch in 0.8.3.
422 active-gtk-theme
424 Is true if the name of the current GTK theme (via
425 org.gnome.desktop.interface GSetting) matches the extension
426 point basename. Added 0.10.1.
427 have-intel-gpu
429 Is true if the i915 kernel module is loaded. Added 0.10.1.
430 on-xdg-desktop-*
432 Is true if the suffix (case-insensitively) is in the
433 XDG_CURRENT_DESKTOP env var. For example
434 on-xdg-desktop-GNOME-classic. Added 1.1.1.
435 autoprune-unless (string)
437 A condition that must be false for the extension to be considered
438 unused when pruning. For example, flatpak uninstall --unused uses
439 this information. The only currently recognized value is
440 active-gl-driver, which is true if the name of the active GL driver
441 matches the extension point basename. Available since 0.11.8.
442 enable-if (string)
444 A condition that must be true for the extension to be enabled. As
445 of 1.1.1 this supports multiple conditions separated by
446 semi-colons. See download-if for available conditions.
447 subdirectory-suffix (string)
449 A suffix that gets appended to the directory name. This is very
450 useful when the extension point naming scheme is "reversed". For
451 example, an extension point for GTK+ themes would be
452 /usr/share/themes/$NAME/gtk-3.0, which could be achieved using
453 subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported
454 to the 0.8.x branch in 0.8.3.
455 subdirectories (boolean)
457 If this key is set to true, then flatpak will look for extensions
458 whose name is a prefix of the extension point name, and mount them
459 at the corresponding name below the subdirectory. Available since
460 0.1.
461 no-autodownload (boolean)
463 Whether to automatically download extensions matching this
464 extension point when updating or installing a 'related' application
465 or runtime. Available since 0.6.7.
466 locale-subset (boolean)
468 If set, then the extensions are partially downloaded by default,
469 based on the currently configured locales. This means that the
470 extension contents should be a set of directories with the language
471 code as name. Available since 0.9.13 (and 0.6.6 for any extensions
472 called *.Locale)
473 autodelete (boolean)
475 Whether to automatically delete extensions matching this extension
476 point when deleting a 'related' application or runtime. Available
477 since 0.6.7.
478 collection-id (string)
480 The ID of the collection that this extension point belongs to. If
481 this is unspecified, it defaults to the collection ID of the
482 application or runtime that the extension point is for. Currently,
483 extension points must be in the same collection as the application
484 or runtime that they are for. Available since 0.99.1.
485 [ExtensionOf]
487 This optional group may be present if the runtime is an extension.
488 ref (string)
490 The ref of the runtime or application that this extension belongs
491 to. Available since 0.9.1.
492 runtime (string)
494 The runtime this extension will be inside of. If it is an app
495 extension, this is the app's runtime; otherwise, this is identical
496 to ref, without the runtime/ prefix. Available since 1.5.0.
497 priority (integer)
499 The priority to give this extension when looking for the best
500 match. Default is 0. Available since 0.9.1, and backported to the
501 0.8.x branch in 0.8.3.
502 tag (string)
504 The tag name to use when searching for this extension's mount point
505 in the parent flatpak. Available since 0.11.4.
506 [Extra Data]
508 This optional group may be present if the runtime or application uses
509 extra data that gets downloaded separately. The data in this group gets
510 merged into the repository summary, with the xa.extra-data-sources key.
511 If multiple extra data sources are present, their uri, size and
513 checksum keys are grouped together by using the same suffix. If only
514 one extra data source is present, the suffix can be omitted.
515 NoRuntime (boolean)
517 Whether to mount the runtime while running the /app/bin/apply_extra
518 script. Defaults to true, i.e. not mounting the runtime. Available
519 since 0.9.1, and backported to the 0.8.x branch in 0.8.4.
520 uriX (string)
522 The uri for extra data source X. The only supported uri schemes are
523 http and https. Available since 0.6.13.
524 sizeX (integer)
526 The size for extra data source X. Available since 0.6.13.
527 checksumX (string)
529 The sha256 sum for extra data source X. Available since 0.6.13.
530 [Policy SUBSYSTEM]
532 Subsystems can define their own policies to be placed in a group whose
533 name has this form. Their values are treated as lists, in which items
534 can have their meaning negated by prepending ! to the value. They are
535 not otherwise parsed by Flatpak. Available since 0.6.13.
536
538 [Application]
539 name=org.gnome.Calculator
540 runtime=org.gnome.Platform/x86_64/3.20
541 sdk=org.gnome.Sdk/x86_64/3.20
542 command=gnome-calculator
543 [Context]
545 shared=network;ipc;
546 sockets=x11;wayland;
547 filesystems=xdg-run/dconf;~/.config/dconf:ro;
548 [Session Bus Policy]
550 ca.desrt.dconf=talk
551 [Environment]
553 DCONF_USER_CONFIG_DIR=.config/dconf
554 [Extension org.gnome.Calculator.Locale]
556 directory=share/runtime/locale
557 subdirectories=true
558 [Extension org.gnome.Calculator.Debug]
560 directory=lib/debug
561
563 flatpak(1), flatpak-run(1), flatpak-override(1)
564
566 1. freedesktop.org special directories
567 https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
568 2. freedesktop.org Base Directory Specification
570 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
571flatpak FLATPAK METADATA(5)