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