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)
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 tags (string list)
56 Tags to include in AppStream XML. Available since 0.4.12.
57 [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 All keys in this group (and the group itself) are optional.
63 shared (list)
65 List of subsystems to share with the host system. Possible
66 subsystems: network, ipc. Available since 0.3.
67 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, pcsc. When making a socket
72 available, flatpak also sets well-known environment variables like
73 DISPLAY or DBUS_SYSTEM_BUS_ADDRESS to let the application find
74 sockets that are not in a fixed location. Available since 0.3.
75 devices (list)
77 List of devices to make available in the sandbox. Possible values:
78 dri
80 Graphics direct rendering (/dev/dri). Available since 0.3.
81 kvm
83 Virtualization (/dev/kvm). Available since 0.6.12.
84 all
86 All device nodes in /dev. Available since 0.6.6.
87 filesystems (list)
90 List of filesystem subsets to make available to the application.
91 Possible values:
92 home
94 The entire home directory. Available since 0.3.
95 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 /dev is not shared: use devices=all; instead.
102 Parts of /sys are always shared. This option does not make
104 additional files in /sys available.
105 These other reserved directories are currently excluded: /app,
107 /bin, /boot, /etc, /lib, /lib32, /lib64, /proc, /root, /run,
108 /sbin, /tmp, /usr, /var.
109 Available since 0.3.
111 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 xdg-desktop/path, xdg-documents/path, etc.
117 Subdirectories of freedesktop.org special directories.
118 Available since 0.4.13.
119 xdg-cache, xdg-config, xdg-data
121 Directories defined by the freedesktop.org Base Directory
122 Specification[2]. Available since 0.6.14.
123 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 xdg-run/path
129 Subdirectories of the XDG_RUNTIME_DIR defined by the
130 freedesktop.org Base Directory Specification. Note that xdg-run
131 on its own is not supported. Available since 0.4.13.
132 /path
134 An arbitrary absolute path. Available since 0.3.
135 ~/path
137 An arbitrary path relative to the home directory. Available
138 since 0.3.
139 One of the above followed by :ro
141 Make the given directory available read-only.
142 One of the above followed by :rw
144 Make the given directory available read/write. This is the
145 default.
146 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 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 features (list)
163 List of features available or unavailable to the application,
164 currently from the following list:
165 devel
167 Allow system calls used by development-oriented tools such as
168 perf, strace and gdb. Available since 0.6.10.
169 multiarch
171 Allow running multilib/multiarch binaries, for example i386
172 binaries in an x86_64 environment. Available since 0.6.12.
173 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 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 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 [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 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 instance-path (string)
199 The absolute path on the host system of the app's persistent
200 storage area in $HOME/.var.
201 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 app-commit (string)
207 The commit ID or the application that is running.
208 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 branch (string)
214 The branch of the app, for example stable. Available since 0.6.10.
215 arch (string)
217 The architecture of the running instance.
218 flatpak-version (string)
220 The version number of the Flatpak version that ran this app.
221 Available since 0.6.11.
222 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 runtime-commit (string)
228 The commit ID or the runtime that is used.
229 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 extra-args (string)
235 Extra arguments that were passed to flatpak run.
236 sandbox (boolean)
238 Whether the --sandbox option was passed to flatpak run.
239 build (boolean)
241 Whether this instance was created by flatpak build.
242 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 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 [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 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 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 If the [Session Bus Policy] group is present, it provides policy for
269 session bus access.
270 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 The possible values for entry are, in increasing order or access:
276 none
278 The bus name or names in question is invisible to the application.
279 Available since 0.2.
280 see
282 The bus name or names can be enumerated by the application.
283 Available since 0.2.
284 talk
286 The application can send messages/ and receive replies and signals
287 from the bus name or names. Available since 0.2.
288 own
290 The application can own the bus name or names (as well as all the
291 above). Available since 0.2.
292 [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 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 [Environment]
303 The [Environment] group specifies environment variables to set when
304 running the application. Available since 0.3.
305 Entries in this group have the form VAR=VALUE where VAR is the name of
307 an environment variable to set.
308 [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 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 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 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 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 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 download-if (string)
349 A condition that must be true for the extension to be
350 auto-downloaded. As of 1.1.1 this supports multiple conditions
351 separated by semi-colons.
352 These are the supported conditions:
354 active-gl-driver
356 Is true if the name of the active GL driver matches the
357 extension point basename. Available since 0.9.1, and backported
358 to the 0.8.x branch in 0.8.3.
359 active-gtk-theme
361 Is true if the name of the current GTK theme (via
362 org.gnome.desktop.interface GSetting) matches the extension
363 point basename. Added 0.10.1.
364 have-intel-gpu
366 Is true if the i915 kernel module is loaded. Added 0.10.1.
367 on-xdg-desktop-*
369 Is true if the suffix (case-insensitively) is in the
370 XDG_CURRENT_DESKTOP env var. For example
371 on-xdg-desktop-GNOME-classic. Added 1.1.1.
372 autoprune-unless (string)
374 A condition that must be false for the extension to be considered
375 unused when pruning. For example, flatpak uninstall --unused uses
376 this information. The only currently recognized value is
377 active-gl-driver, which is true if the name of the active GL driver
378 matches the extension point basename. Available since 0.11.8.
379 enable-if (string)
381 A condition that must be true for the extension to be enabled. As
382 of 1.1.1 this supports multiple conditions separated by
383 semi-colons. See download-if for available conditions.
384 subdirectory-suffix (string)
386 A suffix that gets appended to the directory name. This is very
387 useful when the extension point naming scheme is "reversed". For
388 example, an extension point for GTK+ themes would be
389 /usr/share/themes/$NAME/gtk-3.0, which could be achieved using
390 subdirectory-suffix=gtk-3.0. Available since 0.9.1, and backported
391 to the 0.8.x branch in 0.8.3.
392 subdirectories (boolean)
394 If this key is set to true, then flatpak will look for extensions
395 whose name is a prefix of the extension point name, and mount them
396 at the corresponding name below the subdirectory. Available since
397 0.1.
398 no-autodownload (boolean)
400 Whether to automatically download extensions matching this
401 extension point when updating or installing a 'related' application
402 or runtime. Available since 0.6.7.
403 locale-subset (boolean)
405 If set, then the extensions are partially downloaded by default,
406 based on the currently configured locales. This means that the
407 extension contents should be a set of directories with the language
408 code as name. Available since 0.9.13 (and 0.6.6 for any extensions
409 called *.Locale)
410 autodelete (boolean)
412 Whether to automatically delete extensions matching this extension
413 point when deleting a 'related' application or runtime. Available
414 since 0.6.7.
415 collection-id (string)
417 The ID of the collection that this extension point belongs to. If
418 this is unspecified, it defaults to the collection ID of the
419 application or runtime that the extension point is for. Currently,
420 extension points must be in the same collection as the application
421 or runtime that they are for. Available since 0.99.1.
422 [ExtensionOf]
424 This optional group may be present if the runtime is an extension.
425 ref (string)
427 The ref of the runtime or application that this extension belongs
428 to. Available since 0.9.1.
429 priority (integer)
431 The priority to give this extension when looking for the best
432 match. Default is 0. Available since 0.9.1, and backported to the
433 0.8.x branch in 0.8.3.
434 tag (string)
436 The tag name to use when searching for this extension's mount point
437 in the parent flatpak. Available since 0.11.4.
438 [Extra Data]
440 This optional group may be present if the runtime or application uses
441 extra data that gets downloaded separately. The data in this group gets
442 merged into the repository summary, with the xa.extra-data-sources key.
443 If multiple extra data sources are present, their uri, size and
445 checksum keys are grouped together by using the same suffix. If only
446 one extra data source is present, the suffix can be omitted.
447 NoRuntime (boolean)
449 Whether to mount the runtime while running the /app/bin/apply_extra
450 script. Defaults to true, i.e. not mounting the runtime. Available
451 since 0.9.1, and backported to the 0.8.x branch in 0.8.4.
452 uriX (string)
454 The uri for extra data source X. The only supported uri schemes are
455 http and https. Available since 0.6.13.
456 sizeX (integer)
458 The size for extra data source X. Available since 0.6.13.
459 checksumX (string)
461 The sha256 sum for extra data source X. Available since 0.6.13.
462 [Policy SUBSYSTEM]
464 Subsystems can define their own policies to be placed in a group whose
465 name has this form. Their values are treated as lists, in which items
466 can have their meaning negated by prepending ! to the value. They are
467 not otherwise parsed by Flatpak. Available since 0.6.13.
468
470 [Application]
471 name=org.gnome.Calculator
472 runtime=org.gnome.Platform/x86_64/3.20
473 sdk=org.gnome.Sdk/x86_64/3.20
474 command=gnome-calculator
475 [Context]
477 shared=network;ipc;
478 sockets=x11;wayland;
479 filesystems=xdg-run/dconf;~/.config/dconf:ro;
480 [Session Bus Policy]
482 ca.desrt.dconf=talk
483 [Environment]
485 DCONF_USER_CONFIG_DIR=.config/dconf
486 [Extension org.gnome.Calculator.Locale]
488 directory=share/runtime/locale
489 subdirectories=true
490 [Extension org.gnome.Calculator.Debug]
492 directory=lib/debug
493
495 flatpak(1), flatpak-run(1), flatpak-override(1)
496
498 1. freedesktop.org special directories
499 https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
500 2. freedesktop.org Base Directory Specification
502 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
503flatpak FLATPAK METADATA(5)