1FLATPAK RUN(1)                    flatpak run                   FLATPAK RUN(1)
2
3
4

NAME

6       flatpak-run - Run an application or open a shell in a runtime
7

SYNOPSIS

9       flatpak run [OPTION...] REF [ARG...]
10

DESCRIPTION

12       If REF names an installed application, flatpak runs the application in
13       a sandboxed environment. Extra arguments are passed on to the
14       application.
15
16       If REF names a runtime, a shell is opened in the runtime. This is
17       useful for development and testing.
18
19       By default, flatpak will look for the application or runtime in all
20       per-user and system installations. This can be overridden with the
21       --user, --system and --installation options.
22
23       flatpak creates a sandboxed environment for the application to run in
24       by mounting the right runtime at /usr and a writable directory at /var,
25       whose content is preserved between application runs. The application
26       itself is mounted at /app.
27
28       The details of the sandboxed environment are controlled by the
29       application metadata and various options like --share and --socket that
30       are passed to the run command: Access is allowed if it was requested
31       either in the application metadata file or with an option and the user
32       hasn't overridden it.
33
34       The remaining arguments are passed to the command that gets run in the
35       sandboxed environment. See the --file-forwarding option for handling of
36       file arguments.
37
38       Environment variables are generally passed on to the sandboxed
39       application, with certain exceptions. The application metadata can
40       override environment variables, as well as the --env option. Apart from
41       that, Flatpak always unsets or overrides the following variables, since
42       their session values are likely to interfere with the functioning of
43       the sandbox:
44           PATH
45           LD_LIBRARY_PATH
46           XDG_CONFIG_DIRS
47           XDG_DATA_DIRS
48           SHELL
49           TMPDIR
50           PYTHONPATH
51           PERLLIB
52           PERL5LIB
53           XCURSOR_PATH
54
55       Flatpak also overrides the XDG environment variables to point sandboxed
56       applications at their writable filesystem locations below
57       ~/.var/app/$APPID/:
58           XDG_DATA_HOME
59           XDG_CONFIG_HOME
60           XDG_CACHE_HOME
61
62       The host values of these variables are made available inside the
63       sandbox via these HOST_-prefixed variables:
64           HOST_XDG_DATA_HOME
65           HOST_XDG_CONFIG_HOME
66           HOST_XDG_CACHE_HOME
67
68       Flatpak sets the environment variable FLATPAK_ID to the application ID
69       of the running app.
70
71       Flatpak also bind-mounts as read-only the host's /etc/os-release (if
72       available, or /usr/lib/os-release as a fallback) to
73       /run/host/os-release in accordance with the os-release
74       specification[1].
75
76       If parental controls support is enabled, flatpak will check the current
77       user’s parental controls settings, and will refuse to run an app if it
78       is blocklisted for the current user.
79

OPTIONS

81       The following options are understood:
82
83       -h, --help
84           Show help options and exit.
85
86       --user
87           Look for the application and runtime in per-user installations.
88
89       --system
90           Look for the application and runtime in the default system-wide
91           installations.
92
93       --installation=NAME
94           Look for the application and runtime in the system-wide
95           installation specified by NAME among those defined in
96           /etc/flatpak/installations.d/. Using --installation=default is
97           equivalent to using --system.
98
99       -v, --verbose
100           Print debug information during command processing.
101
102       --ostree-verbose
103           Print OSTree debug information during command processing.
104
105       --arch=ARCH
106           The architecture to run. See flatpak --supported-arches for
107           architectures supported by the host.
108
109       --command=COMMAND
110           The command to run instead of the one listed in the application
111           metadata.
112
113       --cwd=DIR
114           The directory to run the command in. Note that this must be a
115           directory inside the sandbox.
116
117       --branch=BRANCH
118           The branch to use.
119
120       -d, --devel
121           Use the devel runtime that is specified in the application metadata
122           instead of the regular runtime, and use a seccomp profile that is
123           less likely to break development tools.
124
125       --runtime=RUNTIME
126           Use this runtime instead of the one that is specified in the
127           application metadata. This is a full tuple, like for example
128           org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
129           empty or missing parts are filled in with the corresponding values
130           specified by the app.
131
132       --runtime-version=VERSION
133           Use this version of the runtime instead of the one that is
134           specified in the application metadata. This overrides any version
135           specified with the --runtime option.
136
137       --share=SUBSYSTEM
138           Share a subsystem with the host session. This overrides the Context
139           section from the application metadata.  SUBSYSTEM must be one of:
140           network, ipc. This option can be used multiple times.
141
142       --unshare=SUBSYSTEM
143           Don't share a subsystem with the host session. This overrides the
144           Context section from the application metadata.  SUBSYSTEM must be
145           one of: network, ipc. This option can be used multiple times.
146
147       --socket=SOCKET
148           Expose a well known socket to the application. This overrides to
149           the Context section from the application metadata.  SOCKET must be
150           one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
151           session-bus, ssh-auth, pcsc, cups. This option can be used multiple
152           times.
153
154       --nosocket=SOCKET
155           Don't expose a well known socket to the application. This overrides
156           to the Context section from the application metadata.  SOCKET must
157           be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
158           session-bus, ssh-auth, pcsc, cups. This option can be used multiple
159           times.
160
161       --device=DEVICE
162           Expose a device to the application. This overrides to the Context
163           section from the application metadata.  DEVICE must be one of: dri,
164           kvm, shm, all. This option can be used multiple times.
165
166       --nodevice=DEVICE
167           Don't expose a device to the application. This overrides to the
168           Context section from the application metadata.  DEVICE must be one
169           of: dri, kvm, shm, all. This option can be used multiple times.
170
171       --allow=FEATURE
172           Allow access to a specific feature. This overrides to the Context
173           section from the application metadata.  FEATURE must be one of:
174           devel, multiarch, bluetooth. This option can be used multiple
175           times.
176
177           See flatpak-build-finish(1) for the meaning of the various
178           features.
179
180       --disallow=FEATURE
181           Disallow access to a specific feature. This overrides to the
182           Context section from the application metadata.  FEATURE must be one
183           of: devel, multiarch, bluetooth. This option can be used multiple
184           times.
185
186       --filesystem=FILESYSTEM
187           Allow the application access to a subset of the filesystem. This
188           overrides to the Context section from the application metadata.
189           FILESYSTEM can be one of: home, host, host-os, host-etc,
190           xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
191           xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config,
192           xdg-cache, xdg-data, an absolute path, or a homedir-relative path
193           like ~/dir or paths relative to the xdg dirs, like
194           xdg-download/subdir. The optional :ro suffix indicates that the
195           location will be read-only. The optional :create suffix indicates
196           that the location will be read-write and created if it doesn't
197           exist. This option can be used multiple times. See the "[Context]
198           filesystems" list in flatpak-metadata(5) for details of the
199           meanings of these filesystems.
200
201       --nofilesystem=FILESYSTEM
202           Undo the effect of a previous --filesystem=FILESYSTEM in the app's
203           manifest and/or the overrides set up with flatpak-override(1). This
204           overrides the Context section of the application metadata.
205           FILESYSTEM can take the same values as for --filesystem, but the
206           :ro and :create suffixes are not used here. This option can be used
207           multiple times.
208
209           This option does not prevent access to a more narrowly-scoped
210           --filesystem. For example, if an application has the equivalent of
211           --filesystem=xdg-config/MyApp in its manifest or as a system-wide
212           override, and flatpak override --user --nofilesystem=home as a
213           per-user override, then it will be prevented from accessing most of
214           the home directory, but it will still be allowed to access
215           $XDG_CONFIG_HOME/MyApp.
216
217           As a special case, --nofilesystem=host:reset will ignore all
218           --filesystem permissions inherited from the app manifest or
219           flatpak-override(1), in addition to having the behaviour of
220           --nofilesystem=host.
221
222       --add-policy=SUBSYSTEM.KEY=VALUE
223           Add generic policy option. For example,
224           "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
225           map to this metadata:
226
227               [Policy subsystem]
228               key=v1;v2;
229
230
231           This option can be used multiple times.
232
233       --remove-policy=SUBSYSTEM.KEY=VALUE
234           Remove generic policy option. This option can be used multiple
235           times.
236
237       --env=VAR=VALUE
238           Set an environment variable in the application. This overrides to
239           the Context section from the application metadata. This option can
240           be used multiple times.
241
242       --unset-env=VAR
243           Unset an environment variable in the application. This overrides
244           the unset-environment entry in the [Context] group of the metadata,
245           and the [Environment] group. This option can be used multiple
246           times.
247
248       --env-fd=FD
249           Read environment variables from the file descriptor FD, and set
250           them as if via --env. This can be used to avoid environment
251           variables and their values becoming visible to other users.
252
253           Each environment variable is in the form VAR=VALUE followed by a
254           zero byte. This is the same format used by env -0 and
255           /proc/*/environ.
256
257       --own-name=NAME
258           Allow the application to own the well known name NAME on the
259           session bus. If NAME ends with .*, it allows the application to own
260           all matching names. This overrides to the Context section from the
261           application metadata. This option can be used multiple times.
262
263       --talk-name=NAME
264           Allow the application to talk to the well known name NAME on the
265           session bus. If NAME ends with .*, it allows the application to
266           talk to all matching names. This overrides to the Context section
267           from the application metadata. This option can be used multiple
268           times.
269
270       --no-talk-name=NAME
271           Don't allow the application to talk to the well known name NAME on
272           the session bus. If NAME ends with .*, it allows the application to
273           talk to all matching names. This overrides to the Context section
274           from the application metadata. This option can be used multiple
275           times.
276
277       --system-own-name=NAME
278           Allow the application to own the well known name NAME on the system
279           bus. If NAME ends with .*, it allows the application to own all
280           matching names. This overrides to the Context section from the
281           application metadata. This option can be used multiple times.
282
283       --system-talk-name=NAME
284           Allow the application to talk to the well known name NAME on the
285           system bus. If NAME ends with .*, it allows the application to talk
286           to all matching names. This overrides to the Context section from
287           the application metadata. This option can be used multiple times.
288
289       --system-no-talk-name=NAME
290           Don't allow the application to talk to the well known name NAME on
291           the system bus. If NAME ends with .*, it allows the application to
292           talk to all matching names. This overrides to the Context section
293           from the application metadata. This option can be used multiple
294           times.
295
296       --persist=FILENAME
297           If the application doesn't have access to the real homedir, make
298           the (homedir-relative) path FILENAME a bind mount to the
299           corresponding path in the per-application directory, allowing that
300           location to be used for persistent data. This overrides to the
301           Context section from the application metadata. This option can be
302           used multiple times.
303
304       --no-session-bus
305           Run this instance without the filtered access to the session dbus
306           connection. Note, this is the default when run with --sandbox.
307
308       --session-bus
309           Allow filtered access to the session dbus connection. This is the
310           default, except when run with --sandbox.
311
312           Isandbox mode, even if you allow access to the session bus the
313           sandbox cannot talk to or own the application ids (org.the.App.*)
314           on the bus (unless explicitly added), only names in the .Sandbox
315           subset (org.the.App.Sandbox.*).
316
317       --no-a11y-bus
318           Run this instance without the access to the accessibility bus.
319           Note, this is the default when run with --sandbox.
320
321       --a11y-bus
322           Allow access to the accessibility bus. This is the default, except
323           when run with --sandbox.
324
325       --sandbox
326           Run the application in sandboxed mode, which means dropping all the
327           extra permissions it would otherwise have, as well as access to the
328           session/system/a11y busses and document portal.
329
330       --log-session-bus
331           Log session bus traffic. This can be useful to see what access you
332           need to allow in your D-Bus policy.
333
334       --log-system-bus
335           Log system bus traffic. This can be useful to see what access you
336           need to allow in your D-Bus policy.
337
338       -p, --die-with-parent
339           Kill the entire sandbox when the launching process dies.
340
341       --parent-pid=PID
342           Specifies the pid of the "parent" flatpak, used by
343           --parent-expose-pids and --parent-share-pids.
344
345       --parent-expose-pids
346           Make the processes of the new sandbox visible in the sandbox of the
347           parent flatpak, as defined by --parent-pid.
348
349       --parent-share-pids
350           Use the same process ID namespace for the processes of the new
351           sandbox and the sandbox of the parent flatpak, as defined by
352           --parent-pid. Implies --parent-expose-pids.
353
354       --instance-id-fd
355           Write the instance ID string to the given file descriptor.
356
357       --file-forwarding
358           If this option is specified, the remaining arguments are scanned,
359           and all arguments that are enclosed between a pair of '@@'
360           arguments are interpreted as file paths, exported in the document
361           store, and passed to the command in the form of the resulting
362           document path. Arguments between '@@u' and '@@' are considered
363           uris, and any file: uris are exported. The exports are
364           non-persistent and with read and write permissions for the
365           application.
366
367       --app-path=PATH
368           Instead of mounting the app's content on /app in the sandbox, mount
369           PATH on /app, and the app's content on /run/parent/app. If the app
370           has extensions, they will also be redirected into /run/parent/app,
371           and will not be included in the LD_LIBRARY_PATH inside the sandbox.
372
373       --app-path=
374           As a special case, --app-path= (with an empty PATH) results in an
375           empty directory being mounted on /app.
376
377       --usr-path=PATH
378           Instead of mounting the runtime's files on /usr in the sandbox,
379           mount PATH on /usr, and the runtime's normal files on
380           /run/parent/usr. If the runtime has extensions, they will also be
381           redirected into /run/parent/usr, and will not be included in the
382           LD_LIBRARY_PATH inside the sandbox.  This option will usually only
383           be useful if it is combined with --app-path= and
384           --env=LD_LIBRARY_PATH=....
385

EXAMPLES

387       $ flatpak run org.gnome.gedit
388
389       $ flatpak run --devel --command=bash org.gnome.Builder
390
391       $ flatpak run --command=bash org.gnome.Sdk
392

SEE ALSO

394       flatpak(1), flatpak-override(1), flatpak-enter(1)
395

NOTES

397        1. os-release specification
398           https://www.freedesktop.org/software/systemd/man/os-release.html
399
400
401
402flatpak                                                         FLATPAK RUN(1)
Impressum