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.
15 If REF names a runtime, a shell is opened in the runtime. This is
17 useful for development and testing.
18 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 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 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 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 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 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 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 Flatpak sets the environment variable FLATPAK_ID to the application ID
69 of the running app.
70 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 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
81 The following options are understood:
82 -h, --help
84 Show help options and exit.
85 --user
87 Look for the application and runtime in per-user installations.
88 --system
90 Look for the application and runtime in the default system-wide
91 installations.
92 --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 -v, --verbose
100 Print debug information during command processing.
101 --ostree-verbose
103 Print OSTree debug information during command processing.
104 --arch=ARCH
106 The architecture to run. See flatpak --supported-arches for
107 architectures supported by the host.
108 --command=COMMAND
110 The command to run instead of the one listed in the application
111 metadata.
112 --cwd=DIR
114 The directory to run the command in. Note that this must be a
115 directory inside the sandbox.
116 --branch=BRANCH
118 The branch to use.
119 -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 --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 --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 --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 --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 --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 --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 --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 --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 --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 See flatpak-build-finish(1) for the meaning of the various
178 features.
179 --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 --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 --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 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 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 --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 [Policy subsystem]
228 key=v1;v2;
229 This option can be used multiple times.
232 --remove-policy=SUBSYSTEM.KEY=VALUE
234 Remove generic policy option. This option can be used multiple
235 times.
236 --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 --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 --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 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 --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 --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 --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 --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 --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 --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 --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 --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 --session-bus
309 Allow filtered access to the session dbus connection. This is the
310 default, except when run with --sandbox.
311 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 --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 --a11y-bus
322 Allow access to the accessibility bus. This is the default, except
323 when run with --sandbox.
324 --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 --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 --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 -p, --die-with-parent
339 Kill the entire sandbox when the launching process dies.
340 --parent-pid=PID
342 Specifies the pid of the "parent" flatpak, used by
343 --parent-expose-pids and --parent-share-pids.
344 --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 --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 --instance-id-fd
355 Write the instance ID string to the given file descriptor.
356 --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 --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 --app-path=
374 As a special case, --app-path= (with an empty PATH) results in an
375 empty directory being mounted on /app.
376 --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
387 $ flatpak run org.gnome.gedit
388 $ flatpak run --devel --command=bash org.gnome.Builder
390 $ flatpak run --command=bash org.gnome.Sdk
392
394 flatpak(1), flatpak-override(1), flatpak-enter(1)
395
397 1. os-release specification
398 https://www.freedesktop.org/software/systemd/man/os-release.html
399flatpak FLATPAK RUN(1)