1FLATPAK RUN(1) flatpak run FLATPAK RUN(1)
2
6 flatpak-run - Run an application or open a shell in a runtime
7
9 flatpak run [OPTION...] REF [ARG...]
10
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 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 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 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 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 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 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 Also several environment variables with the prefix "GST_" that are used
65 by gstreamer are unset (since Flatpak 1.12.5).
66 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 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 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 Flatpak sets the environment variable FLATPAK_ID to the application ID
87 of the running app.
88 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 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
99 The following options are understood:
100 -h, --help
102 Show help options and exit.
103 -u, --user
105 Look for the application and runtime in per-user installations.
106 --system
108 Look for the application and runtime in the default system-wide
109 installations.
110 --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 -v, --verbose
118 Print debug information during command processing.
119 --ostree-verbose
121 Print OSTree debug information during command processing.
122 --arch=ARCH
124 The architecture to run. See flatpak --supported-arches for
125 architectures supported by the host.
126 --command=COMMAND
128 The command to run instead of the one listed in the application
129 metadata.
130 --cwd=DIR
132 The directory to run the command in. Note that this must be a
133 directory inside the sandbox.
134 --branch=BRANCH
136 The branch to use.
137 -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 --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 --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 --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 --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 --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 --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 --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 --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 --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 See flatpak-build-finish(1) for the meaning of the various
196 features.
197 --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 --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 --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 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 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 --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 [Policy subsystem]
246 key=v1;v2;
247 This option can be used multiple times.
250 --remove-policy=SUBSYSTEM.KEY=VALUE
252 Remove generic policy option. This option can be used multiple
253 times.
254 --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 --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 --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 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 --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 --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 --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 --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 --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 --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 --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 --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 --session-bus
327 Allow filtered access to the session dbus connection. This is the
328 default, except when run with --sandbox.
329 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 --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 --a11y-bus
341 Allow access to the accessibility bus. This is the default, except
342 when run with --sandbox.
343 --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 --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 --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 -p, --die-with-parent
358 Kill the entire sandbox when the launching process dies.
359 --parent-pid=PID
361 Specifies the pid of the "parent" flatpak, used by
362 --parent-expose-pids and --parent-share-pids.
363 --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 --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 --instance-id-fd
374 Write the instance ID string to the given file descriptor.
375 --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 --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 --app-path=
393 As a special case, --app-path= (with an empty PATH) results in an
394 empty directory being mounted on /app.
395 --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
406 $ flatpak run org.gnome.gedit
407 $ flatpak run --devel --command=bash org.gnome.Builder
409 $ flatpak run --command=bash org.gnome.Sdk
411
413 flatpak(1), flatpak-override(1), flatpak-enter(1)
414
416 1. os-release specification
417 https://www.freedesktop.org/software/systemd/man/os-release.html
418flatpak FLATPAK RUN(1)