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