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           Remove access to the specified subset of the filesystem from the
203           application. This overrides to the Context section from the
204           application metadata.  FILESYSTEM can be one of: home, host,
205           host-os, host-etc, xdg-desktop, xdg-documents, xdg-download,
206           xdg-music, xdg-pictures, xdg-public-share, xdg-templates,
207           xdg-videos, an absolute path, or a homedir-relative path like
208           ~/dir. This option can be used multiple times.
209
210       --add-policy=SUBSYSTEM.KEY=VALUE
211           Add generic policy option. For example,
212           "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
213           map to this metadata:
214
215               [Policy subsystem]
216               key=v1;v2;
217
218
219           This option can be used multiple times.
220
221       --remove-policy=SUBSYSTEM.KEY=VALUE
222           Remove generic policy option. This option can be used multiple
223           times.
224
225       --env=VAR=VALUE
226           Set an environment variable in the application. This overrides to
227           the Context section from the application metadata. This option can
228           be used multiple times.
229
230       --unset-env=VAR
231           Unset an environment variable in the application. This overrides
232           the unset-environment entry in the [Context] group of the metadata,
233           and the [Environment] group. This option can be used multiple
234           times.
235
236       --env-fd=FD
237           Read environment variables from the file descriptor FD, and set
238           them as if via --env. This can be used to avoid environment
239           variables and their values becoming visible to other users.
240
241           Each environment variable is in the form VAR=VALUE followed by a
242           zero byte. This is the same format used by env -0 and
243           /proc/*/environ.
244
245       --own-name=NAME
246           Allow the application to own the well known name NAME on the
247           session bus. If NAME ends with .*, it allows the application to own
248           all matching names. This overrides to the Context section from the
249           application metadata. This option can be used multiple times.
250
251       --talk-name=NAME
252           Allow the application to talk to the well known name NAME on the
253           session bus. If NAME ends with .*, it allows the application to
254           talk to all matching names. This overrides to the Context section
255           from the application metadata. This option can be used multiple
256           times.
257
258       --no-talk-name=NAME
259           Don't allow the application to talk to the well known name NAME on
260           the session bus. If NAME ends with .*, it allows the application to
261           talk to all matching names. This overrides to the Context section
262           from the application metadata. This option can be used multiple
263           times.
264
265       --system-own-name=NAME
266           Allow the application to own the well known name NAME on the system
267           bus. If NAME ends with .*, it allows the application to own all
268           matching names. This overrides to the Context section from the
269           application metadata. This option can be used multiple times.
270
271       --system-talk-name=NAME
272           Allow the application to talk to the well known name NAME on the
273           system bus. If NAME ends with .*, it allows the application to talk
274           to all matching names. This overrides to the Context section from
275           the application metadata. This option can be used multiple times.
276
277       --system-no-talk-name=NAME
278           Don't allow the application to talk to the well known name NAME on
279           the system bus. If NAME ends with .*, it allows the application to
280           talk to all matching names. This overrides to the Context section
281           from the application metadata. This option can be used multiple
282           times.
283
284       --persist=FILENAME
285           If the application doesn't have access to the real homedir, make
286           the (homedir-relative) path FILENAME a bind mount to the
287           corresponding path in the per-application directory, allowing that
288           location to be used for persistent data. This overrides to the
289           Context section from the application metadata. This option can be
290           used multiple times.
291
292       --no-session-bus
293           Run this instance without the filtered access to the session dbus
294           connection. Note, this is the default when run with --sandbox.
295
296       --session-bus
297           Allow filtered access to the session dbus connection. This is the
298           default, except when run with --sandbox.
299
300           Isandbox mode, even if you allow access to the session bus the
301           sandbox cannot talk to or own the application ids (org.the.App.*)
302           on the bus (unless explicitly added), only names in the .Sandbox
303           subset (org.the.App.Sandbox.*).
304
305       --no-a11y-bus
306           Run this instance without the access to the accessibility bus.
307           Note, this is the default when run with --sandbox.
308
309       --a11y-bus
310           Allow access to the accessibility bus. This is the default, except
311           when run with --sandbox.
312
313       --sandbox
314           Run the application in sandboxed mode, which means dropping all the
315           extra permissions it would otherwise have, as well as access to the
316           session/system/a11y busses and document portal.
317
318       --log-session-bus
319           Log session bus traffic. This can be useful to see what access you
320           need to allow in your D-Bus policy.
321
322       --log-system-bus
323           Log system bus traffic. This can be useful to see what access you
324           need to allow in your D-Bus policy.
325
326       -p, --die-with-parent
327           Kill the entire sandbox when the launching process dies.
328
329       --parent-pid=PID
330           Specifies the pid of the "parent" flatpak, used by
331           --parent-expose-pids and --parent-share-pids.
332
333       --parent-expose-pids
334           Make the processes of the new sandbox visible in the sandbox of the
335           parent flatpak, as defined by --parent-pid.
336
337       --parent-share-pids
338           Use the same process ID namespace for the processes of the new
339           sandbox and the sandbox of the parent flatpak, as defined by
340           --parent-pid. Implies --parent-expose-pids.
341
342       --instance-id-fd
343           Write the instance ID string to the given file descriptor.
344
345       --file-forwarding
346           If this option is specified, the remaining arguments are scanned,
347           and all arguments that are enclosed between a pair of '@@'
348           arguments are interpreted as file paths, exported in the document
349           store, and passed to the command in the form of the resulting
350           document path. Arguments between '@@u' and '@@' are considered
351           uris, and any file: uris are exported. The exports are
352           non-persistent and with read and write permissions for the
353           application.
354
355       --app-path=PATH
356           Instead of mounting the app's content on /app in the sandbox, mount
357           PATH on /app, and the app's content on /run/parent/app. If the app
358           has extensions, they will also be redirected into /run/parent/app,
359           and will not be included in the LD_LIBRARY_PATH inside the sandbox.
360
361       --app-path=
362           As a special case, --app-path= (with an empty PATH) results in an
363           empty directory being mounted on /app.
364
365       --usr-path=PATH
366           Instead of mounting the runtime's files on /usr in the sandbox,
367           mount PATH on /usr, and the runtime's normal files on
368           /run/parent/usr. If the runtime has extensions, they will also be
369           redirected into /run/parent/usr, and will not be included in the
370           LD_LIBRARY_PATH inside the sandbox.  This option will usually only
371           be useful if it is combined with --app-path= and
372           --env=LD_LIBRARY_PATH=....
373

EXAMPLES

375       $ flatpak run org.gnome.gedit
376
377       $ flatpak run --devel --command=bash org.gnome.Builder
378
379       $ flatpak run --command=bash org.gnome.Sdk
380

SEE ALSO

382       flatpak(1), flatpak-override(1), flatpak-enter(1)
383

NOTES

385        1. os-release specification
386           https://www.freedesktop.org/software/systemd/man/os-release.html
387
388
389
390flatpak                                                         FLATPAK RUN(1)
Impressum