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 XKB_CONFIG_ROOT
64 GIO_EXTRA_MODULES
65 GDK_BACKEND
66 VK_DRIVER_FILES
67 VK_ICD_FILENAMES
68 Also several environment variables with the prefix "GST_" that are used
70 by gstreamer are unset (since Flatpak 1.12.5).
71 Flatpak also overrides the XDG environment variables to point sandboxed
73 applications at their writable filesystem locations below
74 ~/.var/app/$APPID/:
75 XDG_DATA_HOME
76 XDG_CONFIG_HOME
77 XDG_CACHE_HOME
78 XDG_STATE_HOME (since Flatpak 1.13)
79 Apps can use the --persist=.local/state and --unset-env=XDG_STATE_HOME
81 options to get a Flatpak 1.13-compatible ~/.local/state on older
82 versions of Flatpak.
83 The host values of these variables are made available inside the
85 sandbox via these HOST_-prefixed variables:
86 HOST_XDG_DATA_HOME
87 HOST_XDG_CONFIG_HOME
88 HOST_XDG_CACHE_HOME
89 HOST_XDG_STATE_HOME (since Flatpak 1.13)
90 Flatpak sets the environment variable FLATPAK_ID to the application ID
92 of the running app.
93 Flatpak also bind-mounts as read-only the host's /etc/os-release (if
95 available, or /usr/lib/os-release as a fallback) to
96 /run/host/os-release in accordance with the os-release
97 specification[1].
98 If parental controls support is enabled, flatpak will check the current
100 user’s parental controls settings, and will refuse to run an app if it
101 is blocklisted for the current user.
102
104 The following options are understood:
105 -h, --help
107 Show help options and exit.
108 -u, --user
110 Look for the application and runtime in per-user installations.
111 --system
113 Look for the application and runtime in the default system-wide
114 installations.
115 --installation=NAME
117 Look for the application and runtime in the system-wide
118 installation specified by NAME among those defined in
119 /etc/flatpak/installations.d/. Using --installation=default is
120 equivalent to using --system.
121 -v, --verbose
123 Print debug information during command processing.
124 --ostree-verbose
126 Print OSTree debug information during command processing.
127 --arch=ARCH
129 The architecture to run. See flatpak --supported-arches for
130 architectures supported by the host.
131 --command=COMMAND
133 The command to run instead of the one listed in the application
134 metadata.
135 --cwd=DIR
137 The directory to run the command in. Note that this must be a
138 directory inside the sandbox.
139 --branch=BRANCH
141 The branch to use.
142 -d, --devel
144 Use the devel runtime that is specified in the application metadata
145 instead of the regular runtime, and use a seccomp profile that is
146 less likely to break development tools.
147 --runtime=RUNTIME
149 Use this runtime instead of the one that is specified in the
150 application metadata. This is a full tuple, like for example
151 org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
152 empty or missing parts are filled in with the corresponding values
153 specified by the app.
154 --runtime-version=VERSION
156 Use this version of the runtime instead of the one that is
157 specified in the application metadata. This overrides any version
158 specified with the --runtime option.
159 --share=SUBSYSTEM
161 Share a subsystem with the host session. This overrides the Context
162 section from the application metadata. SUBSYSTEM must be one of:
163 network, ipc. This option can be used multiple times.
164 --unshare=SUBSYSTEM
166 Don't share a subsystem with the host session. This overrides the
167 Context section from the application metadata. SUBSYSTEM must be
168 one of: network, ipc. This option can be used multiple times.
169 --socket=SOCKET
171 Expose a well known socket to the application. This overrides to
172 the Context section from the application metadata. SOCKET must be
173 one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
174 session-bus, ssh-auth, pcsc, cups, gpg-agent. This option can be
175 used multiple times.
176 --nosocket=SOCKET
178 Don't expose a well known socket to the application. This overrides
179 to the Context section from the application metadata. SOCKET must
180 be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
181 session-bus, ssh-auth, pcsc, cups, gpg-agent. This option can be
182 used multiple times.
183 --device=DEVICE
185 Expose a device to the application. This overrides to the Context
186 section from the application metadata. DEVICE must be one of: dri,
187 input, kvm, shm, all. This option can be used multiple times.
188 --nodevice=DEVICE
190 Don't expose a device to the application. This overrides to the
191 Context section from the application metadata. DEVICE must be one
192 of: dri, input, kvm, shm, all. This option can be used multiple
193 times.
194 --allow=FEATURE
196 Allow access to a specific feature. This overrides to the Context
197 section from the application metadata. FEATURE must be one of:
198 devel, multiarch, bluetooth. This option can be used multiple
199 times.
200 See flatpak-build-finish(1) for the meaning of the various
202 features.
203 --disallow=FEATURE
205 Disallow access to a specific feature. This overrides to the
206 Context section from the application metadata. FEATURE must be one
207 of: devel, multiarch, bluetooth. This option can be used multiple
208 times.
209 --filesystem=FILESYSTEM
211 Allow the application access to a subset of the filesystem. This
212 overrides to the Context section from the application metadata.
213 FILESYSTEM can be one of: home, host, host-os, host-etc,
214 xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
215 xdg-public-share, xdg-templates, xdg-videos, xdg-run, xdg-config,
216 xdg-cache, xdg-data, an absolute path, or a homedir-relative path
217 like ~/dir or paths relative to the xdg dirs, like
218 xdg-download/subdir. The optional :ro suffix indicates that the
219 location will be read-only. The optional :create suffix indicates
220 that the location will be read-write and created if it doesn't
221 exist. This option can be used multiple times. See the "[Context]
222 filesystems" list in flatpak-metadata(5) for details of the
223 meanings of these filesystems.
224 --nofilesystem=FILESYSTEM
226 Undo the effect of a previous --filesystem=FILESYSTEM in the app's
227 manifest and/or the overrides set up with flatpak-override(1). This
228 overrides the Context section of the application metadata.
229 FILESYSTEM can take the same values as for --filesystem, but the
230 :ro and :create suffixes are not used here. This option can be used
231 multiple times.
232 This option does not prevent access to a more narrowly-scoped
234 --filesystem. For example, if an application has the equivalent of
235 --filesystem=xdg-config/MyApp in its manifest or as a system-wide
236 override, and flatpak override --user --nofilesystem=home as a
237 per-user override, then it will be prevented from accessing most of
238 the home directory, but it will still be allowed to access
239 $XDG_CONFIG_HOME/MyApp.
240 As a special case, --nofilesystem=host:reset will ignore all
242 --filesystem permissions inherited from the app manifest or
243 flatpak-override(1), in addition to having the behaviour of
244 --nofilesystem=host.
245 --add-policy=SUBSYSTEM.KEY=VALUE
247 Add generic policy option. For example,
248 "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
249 map to this metadata:
250 [Policy subsystem]
252 key=v1;v2;
253 This option can be used multiple times.
256 --remove-policy=SUBSYSTEM.KEY=VALUE
258 Remove generic policy option. This option can be used multiple
259 times.
260 --env=VAR=VALUE
262 Set an environment variable in the application. This overrides to
263 the Context section from the application metadata. This option can
264 be used multiple times.
265 --unset-env=VAR
267 Unset an environment variable in the application. This overrides
268 the unset-environment entry in the [Context] group of the metadata,
269 and the [Environment] group. This option can be used multiple
270 times.
271 --env-fd=FD
273 Read environment variables from the file descriptor FD, and set
274 them as if via --env. This can be used to avoid environment
275 variables and their values becoming visible to other users.
276 Each environment variable is in the form VAR=VALUE followed by a
278 zero byte. This is the same format used by env -0 and
279 /proc/*/environ.
280 --own-name=NAME
282 Allow the application to own the well known name NAME on the
283 session bus. If NAME ends with .*, it allows the application to own
284 all matching names. This overrides to the Context section from the
285 application metadata. This option can be used multiple times.
286 --talk-name=NAME
288 Allow the application to talk to the well known name NAME on the
289 session bus. If NAME ends with .*, it allows the application to
290 talk to all matching names. This overrides to the Context section
291 from the application metadata. This option can be used multiple
292 times.
293 --no-talk-name=NAME
295 Don't allow the application to talk to the well known name NAME on
296 the session bus. If NAME ends with .*, it allows the application to
297 talk to all matching names. This overrides to the Context section
298 from the application metadata. This option can be used multiple
299 times.
300 --system-own-name=NAME
302 Allow the application to own the well known name NAME on the system
303 bus. If NAME ends with .*, it allows the application to own all
304 matching names. This overrides to the Context section from the
305 application metadata. This option can be used multiple times.
306 --system-talk-name=NAME
308 Allow the application to talk to the well known name NAME on the
309 system bus. If NAME ends with .*, it allows the application to talk
310 to all matching names. This overrides to the Context section from
311 the application metadata. This option can be used multiple times.
312 --system-no-talk-name=NAME
314 Don't allow the application to talk to the well known name NAME on
315 the system bus. If NAME ends with .*, it allows the application to
316 talk to all matching names. This overrides to the Context section
317 from the application metadata. This option can be used multiple
318 times.
319 --persist=FILENAME
321 If the application doesn't have access to the real homedir, make
322 the (homedir-relative) path FILENAME a bind mount to the
323 corresponding path in the per-application directory, allowing that
324 location to be used for persistent data. This overrides to the
325 Context section from the application metadata. This option can be
326 used multiple times.
327 --no-session-bus
329 Run this instance without the filtered access to the session dbus
330 connection. Note, this is the default when run with --sandbox.
331 --session-bus
333 Allow filtered access to the session dbus connection. This is the
334 default, except when run with --sandbox.
335 In sandbox mode, even if you allow access to the session bus the
337 sandbox cannot talk to or own the application ids (org.the.App.*)
338 on the bus (unless explicitly added), only names in the .Sandboxed
339 subset (org.the.App.Sandboxed.* and
340 org.mpris.MediaPlayer2.org.the.App.Sandboxed.*).
341 --no-a11y-bus
343 Run this instance without the access to the accessibility bus.
344 Note, this is the default when run with --sandbox.
345 --a11y-bus
347 Allow access to the accessibility bus. This is the default, except
348 when run with --sandbox.
349 --sandbox
351 Run the application in sandboxed mode, which means dropping all the
352 extra permissions it would otherwise have, as well as access to the
353 session/system/a11y busses and document portal.
354 --log-session-bus
356 Log session bus traffic. This can be useful to see what access you
357 need to allow in your D-Bus policy.
358 --log-system-bus
360 Log system bus traffic. This can be useful to see what access you
361 need to allow in your D-Bus policy.
362 -p, --die-with-parent
364 Kill the entire sandbox when the launching process dies.
365 --parent-pid=PID
367 Specifies the pid of the "parent" flatpak, used by
368 --parent-expose-pids and --parent-share-pids.
369 --parent-expose-pids
371 Make the processes of the new sandbox visible in the sandbox of the
372 parent flatpak, as defined by --parent-pid.
373 --parent-share-pids
375 Use the same process ID namespace for the processes of the new
376 sandbox and the sandbox of the parent flatpak, as defined by
377 --parent-pid. Implies --parent-expose-pids.
378 --instance-id-fd
380 Write the instance ID string to the given file descriptor.
381 --file-forwarding
383 If this option is specified, the remaining arguments are scanned,
384 and all arguments that are enclosed between a pair of '@@'
385 arguments are interpreted as file paths, exported in the document
386 store, and passed to the command in the form of the resulting
387 document path. Arguments between '@@u' and '@@' are considered
388 uris, and any file: uris are exported. The exports are
389 non-persistent and with read and write permissions for the
390 application.
391 --app-path=PATH
393 Instead of mounting the app's content on /app in the sandbox, mount
394 PATH on /app, and the app's content on /run/parent/app. If the app
395 has extensions, they will also be redirected into /run/parent/app,
396 and will not be included in the LD_LIBRARY_PATH inside the sandbox.
397 --app-path=
399 As a special case, --app-path= (with an empty PATH) results in an
400 empty directory being mounted on /app.
401 --usr-path=PATH
403 Instead of mounting the runtime's files on /usr in the sandbox,
404 mount PATH on /usr, and the runtime's normal files on
405 /run/parent/usr. If the runtime has extensions, they will also be
406 redirected into /run/parent/usr, and will not be included in the
407 LD_LIBRARY_PATH inside the sandbox. This option will usually only
408 be useful if it is combined with --app-path= and
409 --env=LD_LIBRARY_PATH=....
410
412 $ flatpak run org.gnome.gedit
413 $ flatpak run --devel --command=bash org.gnome.Builder
415 $ flatpak run --command=bash org.gnome.Sdk
417
419 flatpak(1), flatpak-override(1), flatpak-enter(1)
420
422 1. os-release specification
423 https://www.freedesktop.org/software/systemd/man/os-release.html
424flatpak FLATPAK RUN(1)