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. The current branch and arch of the application is used
15       unless otherwise specified with --branch or --arch. See flatpak-make-
16       current(1).
17
18       If REF names a runtime, a shell is opened in the runtime. This is
19       useful for development and testing. If there is ambiguity about which
20       branch to use, you will be prompted to choose. Use --branch to avoid
21       this. The primary arch is used unless otherwise specified with --arch.
22
23       By default, Flatpak will look for the application or runtime in the
24       per-user installation first, then in all system installations. This can
25       be overridden with the --user, --system and --installation options.
26
27       Flatpak creates a sandboxed environment for the application to run in
28       by mounting the right runtime at /usr and a writable directory at /var,
29       whose content is preserved between application runs. The application
30       itself is mounted at /app.
31
32       The details of the sandboxed environment are controlled by the
33       application metadata and various options like --share and --socket that
34       are passed to the run command: Access is allowed if it was requested
35       either in the application metadata file or with an option and the user
36       hasn't overridden it.
37
38       The remaining arguments are passed to the command that gets run in the
39       sandboxed environment. See the --file-forwarding option for handling of
40       file arguments.
41
42       Environment variables are generally passed on to the sandboxed
43       application, with certain exceptions. The application metadata can
44       override environment variables, as well as the --env option. Apart from
45       that, Flatpak always unsets or overrides the following variables, since
46       their session values are likely to interfere with the functioning of
47       the sandbox:
48           PATH
49           LD_LIBRARY_PATH
50           XDG_CONFIG_DIRS
51           XDG_DATA_DIRS
52           XDG_RUNTIME_DIR
53           SHELL
54           TEMP
55           TEMPDIR
56           TMP
57           TMPDIR
58           PYTHONPATH
59           PERLLIB
60           PERL5LIB
61           XCURSOR_PATH
62           KRB5CCNAME
63
64       Also several environment variables with the prefix "GST_" that are used
65       by gstreamer are unset (since Flatpak 1.12.5).
66
67       Flatpak also overrides the XDG environment variables to point sandboxed
68       applications at their writable filesystem locations below
69       ~/.var/app/$APPID/:
70           XDG_DATA_HOME
71           XDG_CONFIG_HOME
72           XDG_CACHE_HOME
73           XDG_STATE_HOME (since Flatpak 1.13)
74
75       Apps can use the --persist=.local/state and --unset-env=XDG_STATE_HOME
76       options to get a Flatpak 1.13-compatible ~/.local/state on older
77       versions of Flatpak.
78
79       The host values of these variables are made available inside the
80       sandbox via these HOST_-prefixed variables:
81           HOST_XDG_DATA_HOME
82           HOST_XDG_CONFIG_HOME
83           HOST_XDG_CACHE_HOME
84           HOST_XDG_STATE_HOME (since Flatpak 1.13)
85
86       Flatpak sets the environment variable FLATPAK_ID to the application ID
87       of the running app.
88
89       Flatpak also bind-mounts as read-only the host's /etc/os-release (if
90       available, or /usr/lib/os-release as a fallback) to
91       /run/host/os-release in accordance with the os-release
92       specification[1].
93
94       If parental controls support is enabled, flatpak will check the current
95       user’s parental controls settings, and will refuse to run an app if it
96       is blocklisted for the current user.
97

OPTIONS

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

EXAMPLES

406       $ flatpak run org.gnome.gedit
407
408       $ flatpak run --devel --command=bash org.gnome.Builder
409
410       $ flatpak run --command=bash org.gnome.Sdk
411

SEE ALSO

413       flatpak(1), flatpak-override(1), flatpak-enter(1)
414

NOTES

416        1. os-release specification
417           https://www.freedesktop.org/software/systemd/man/os-release.html
418
419
420
421flatpak                                                         FLATPAK RUN(1)
Impressum