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 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 --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 [Policy subsystem]
216 key=v1;v2;
217 This option can be used multiple times.
220 --remove-policy=SUBSYSTEM.KEY=VALUE
222 Remove generic policy option. This option can be used multiple
223 times.
224 --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 --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 --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 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 --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 --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 --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 --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 --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 --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 --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 --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 --session-bus
297 Allow filtered access to the session dbus connection. This is the
298 default, except when run with --sandbox.
299 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 --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 --a11y-bus
310 Allow access to the accessibility bus. This is the default, except
311 when run with --sandbox.
312 --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 --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 --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 -p, --die-with-parent
327 Kill the entire sandbox when the launching process dies.
328 --parent-pid=PID
330 Specifies the pid of the "parent" flatpak, used by
331 --parent-expose-pids and --parent-share-pids.
332 --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 --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 --instance-id-fd
343 Write the instance ID string to the given file descriptor.
344 --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 --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 --app-path=
362 As a special case, --app-path= (with an empty PATH) results in an
363 empty directory being mounted on /app.
364 --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
375 $ flatpak run org.gnome.gedit
376 $ flatpak run --devel --command=bash org.gnome.Builder
378 $ flatpak run --command=bash org.gnome.Sdk
380
382 flatpak(1), flatpak-override(1), flatpak-enter(1)
383
385 1. os-release specification
386 https://www.freedesktop.org/software/systemd/man/os-release.html
387flatpak FLATPAK RUN(1)