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 If parental controls support is enabled, flatpak will check the current
72 user’s parental controls settings, and will refuse to run an app if it
73 is blacklisted for the current user.
74
76 The following options are understood:
77 -h, --help
79 Show help options and exit.
80 --user
82 Look for the application and runtime in per-user installations.
83 --system
85 Look for the application and runtime in the default system-wide
86 installations.
87 --installation=NAME
89 Look for the application and runtime in the system-wide
90 installation specified by NAME among those defined in
91 /etc/flatpak/installations.d/. Using --installation=default is
92 equivalent to using --system.
93 -v, --verbose
95 Print debug information during command processing.
96 --ostree-verbose
98 Print OSTree debug information during command processing.
99 --arch=ARCH
101 The architecture to run. See flatpak --supported-arches for
102 architectures supported by the host.
103 --command=COMMAND
105 The command to run instead of the one listed in the application
106 metadata.
107 --cwd=DIR
109 The directory to run the command in. Note that this must be a
110 directory inside the sandbox.
111 --branch=BRANCH
113 The branch to use.
114 -d, --devel
116 Use the devel runtime that is specified in the application metadata
117 instead of the regular runtime, and use a seccomp profile that is
118 less likely to break development tools.
119 --runtime=RUNTIME
121 Use this runtime instead of the one that is specified in the
122 application metadata. This is a full tuple, like for example
123 org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
124 empty or missing parts are filled in with the corresponding values
125 specified by the app.
126 --runtime-version=VERSION
128 Use this version of the runtime instead of the one that is
129 specified in the application metadata. This overrides any version
130 specified with the --runtime option.
131 --share=SUBSYSTEM
133 Share a subsystem with the host session. This overrides the Context
134 section from the application metadata. SUBSYSTEM must be one of:
135 network, ipc. This option can be used multiple times.
136 --unshare=SUBSYSTEM
138 Don't share a subsystem with the host session. This overrides the
139 Context section from the application metadata. SUBSYSTEM must be
140 one of: network, ipc. This option can be used multiple times.
141 --socket=SOCKET
143 Expose a well known socket to the application. This overrides to
144 the Context section from the application metadata. SOCKET must be
145 one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
146 session-bus, ssh-auth, pcsc, cups. This option can be used multiple
147 times.
148 --nosocket=SOCKET
150 Don't expose a well known socket to the application. This overrides
151 to the Context section from the application metadata. SOCKET must
152 be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
153 session-bus, ssh-auth, pcsc, cups. This option can be used multiple
154 times.
155 --device=DEVICE
157 Expose a device to the application. This overrides to the Context
158 section from the application metadata. DEVICE must be one of: dri,
159 kvm, shm, all. This option can be used multiple times.
160 --nodevice=DEVICE
162 Don't expose a device to the application. This overrides to the
163 Context section from the application metadata. DEVICE must be one
164 of: dri, kvm, shm, all. This option can be used multiple times.
165 --allow=FEATURE
167 Allow access to a specific feature. This overrides to the Context
168 section from the application metadata. FEATURE must be one of:
169 devel, multiarch, bluetooth. This option can be used multiple
170 times.
171 See flatpak-build-finish(1) for the meaning of the various
173 features.
174 --disallow=FEATURE
176 Disallow access to a specific feature. This overrides to the
177 Context section from the application metadata. FEATURE must be one
178 of: devel, multiarch, bluetooth. This option can be used multiple
179 times.
180 --filesystem=FILESYSTEM
182 Allow the application access to a subset of the filesystem. This
183 overrides to the Context section from the application metadata.
184 FILESYSTEM can be one of: home, host, xdg-desktop, xdg-documents,
185 xdg-download, xdg-music, xdg-pictures, xdg-public-share,
186 xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache,
187 xdg-data, an absolute path, or a homedir-relative path like ~/dir
188 or paths relative to the xdg dirs, like xdg-download/subdir. The
189 optional :ro suffix indicates that the location will be read-only.
190 The optional :create suffix indicates that the location will be
191 read-write and created if it doesn't exist. This option can be used
192 multiple times. See the "[Context] filesystems" list in flatpak-
193 metadata(5) for details of the meanings of these filesystems.
194 --nofilesystem=FILESYSTEM
196 Remove access to the specified subset of the filesystem from the
197 application. This overrides to the Context section from the
198 application metadata. FILESYSTEM can be one of: home, host,
199 xdg-desktop, xdg-documents, xdg-download, xdg-music, xdg-pictures,
200 xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a
201 homedir-relative path like ~/dir. This option can be used multiple
202 times.
203 --add-policy=SUBSYSTEM.KEY=VALUE
205 Add generic policy option. For example,
206 "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
207 map to this metadata:
208 [Policy subsystem]
210 key=v1;v2;
211 This option can be used multiple times.
214 --remove-policy=SUBSYSTEM.KEY=VALUE
216 Remove generic policy option. This option can be used multiple
217 times.
218 --env=VAR=VALUE
220 Set an environment variable in the application. This overrides to
221 the Context section from the application metadata. This option can
222 be used multiple times.
223 --own-name=NAME
225 Allow the application to own the well known name NAME on the
226 session bus. If NAME ends with .*, it allows the application to own
227 all matching names. This overrides to the Context section from the
228 application metadata. This option can be used multiple times.
229 --talk-name=NAME
231 Allow the application to talk to the well known name NAME on the
232 session bus. If NAME ends with .*, it allows the application to
233 talk to all matching names. This overrides to the Context section
234 from the application metadata. This option can be used multiple
235 times.
236 --no-talk-name=NAME
238 Don't allow the application to talk to the well known name NAME on
239 the session bus. If NAME ends with .*, it allows the application to
240 talk to all matching names. This overrides to the Context section
241 from the application metadata. This option can be used multiple
242 times.
243 --system-own-name=NAME
245 Allow the application to own the well known name NAME on the system
246 bus. If NAME ends with .*, it allows the application to own all
247 matching names. This overrides to the Context section from the
248 application metadata. This option can be used multiple times.
249 --system-talk-name=NAME
251 Allow the application to talk to the well known name NAME on the
252 system bus. If NAME ends with .*, it allows the application to talk
253 to all matching names. This overrides to the Context section from
254 the application metadata. This option can be used multiple times.
255 --system-no-talk-name=NAME
257 Don't allow the application to talk to the well known name NAME on
258 the system bus. If NAME ends with .*, it allows the application to
259 talk to all matching names. This overrides to the Context section
260 from the application metadata. This option can be used multiple
261 times.
262 --persist=FILENAME
264 If the application doesn't have access to the real homedir, make
265 the (homedir-relative) path FILENAME a bind mount to the
266 corresponding path in the per-application directory, allowing that
267 location to be used for persistent data. This overrides to the
268 Context section from the application metadata. This option can be
269 used multiple times.
270 --no-session-bus
272 Run this instance without the filtered access to the session dbus
273 connection. Note, this is the default when run with --sandbox.
274 --session-bus
276 Allow filtered access to the session dbus connection. This is the
277 default, except when run with --sandbox.
278 Isandbox mode, even if you allow access to the session bus the
280 sandbox cannot talk to or own the application ids (org.the.App.*)
281 on the bus (unless explicitly added), only names in the .Sandbox
282 subset (org.the.App.Sandbox.*).
283 --no-a11y-bus
285 Run this instance without the access to the accessibility bus.
286 Note, this is the default when run with --sandbox.
287 --a11y-bus
289 Allow access to the accessibility bus. This is the default, except
290 when run with --sandbox.
291 --sandbox
293 Run the application in sandboxed mode, which means dropping all the
294 extra permissions it would otherwise have, as well as access to the
295 session/system/a11y busses and document portal.
296 --log-session-bus
298 Log session bus traffic. This can be useful to see what access you
299 need to allow in your D-Bus policy.
300 --log-system-bus
302 Log system bus traffic. This can be useful to see what access you
303 need to allow in your D-Bus policy.
304 -p, --die-with-parent
306 Kill the entire sandbox when the launching process dies.
307 --parent-pid=PID
309 Specifies the pid of the "parent" flatpak, used by
310 --parent-expose-pids.
311 --parent-expose-pids
313 Make the processes of the new sandbox visible in the sandbox of the
314 parent flatpak, as defined by --parent-pid.
315 --file-forwarding
317 If this option is specified, the remaining arguments are scanned,
318 and all arguments that are enclosed between a pair of '@@'
319 arguments are interpreted as file paths, exported in the document
320 store, and passed to the command in the form of the resulting
321 document path. Arguments between '@@u' and '@@' are considered
322 uris, and any file: uris are exported. The exports are
323 non-persistent and with read and write permissions for the
324 application.
325
327 $ flatpak run org.gnome.gedit
328 $ flatpak run --devel --command=bash org.gnome.Builder
330 $ flatpak run --command=bash org.gnome.Sdk
332
334 flatpak(1), flatpak-override(1), flatpak-enter(1)
335flatpak FLATPAK RUN(1)