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
56 The following options are understood:
57 -h, --help
59 Show help options and exit.
60 --user
62 Look for the application and runtime in per-user installations.
63 --system
65 Look for the application and runtime in the default system-wide
66 installations.
67 --installation=NAME
69 Look for the application and runtime in the system-wide
70 installation specified by NAME among those defined in
71 /etc/flatpak/installations.d/. Using --installation=default is
72 equivalent to using --system.
73 -v, --verbose
75 Print debug information during command processing.
76 --ostree-verbose
78 Print OSTree debug information during command processing.
79 --arch=ARCH
81 The architecture to install for.
82 --command=COMMAND
84 The command to run instead of the one listed in the application
85 metadata.
86 --branch=BRANCH
88 The branch to use.
89 -d, --devel
91 Use the devel runtime that is specified in the application metadata
92 instead of the regular runtime, and use a seccomp profile that is
93 less likely to break development tools.
94 --runtime=RUNTIME
96 Use this runtime instead of the one that is specified in the
97 application metadata. This is a full tuple, like for example
98 org.freedesktop.Sdk/x86_64/1.2, but partial tuples are allowed. Any
99 empty or missing parts are filled in with the corresponding values
100 specified by the app.
101 --runtime-version=VERSION
103 Use this version of the runtime instead of the one that is
104 specified in the application metadata. This overrides any version
105 specified with the --runtime option.
106 --share=SUBSYSTEM
108 Share a subsystem with the host session. This overrides the Context
109 section from the application metadata. SUBSYSTEM must be one of:
110 network, ipc. This option can be used multiple times.
111 --unshare=SUBSYSTEM
113 Don't share a subsystem with the host session. This overrides the
114 Context section from the application metadata. SUBSYSTEM must be
115 one of: network, ipc. This option can be used multiple times.
116 --socket=SOCKET
118 Expose a well known socket to the application. This overrides to
119 the Context section from the application metadata. SOCKET must be
120 one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
121 session-bus, ssh-auth. This option can be used multiple times.
122 --nosocket=SOCKET
124 Don't expose a well known socket to the application. This overrides
125 to the Context section from the application metadata. SOCKET must
126 be one of: x11, wayland, fallback-x11, pulseaudio, system-bus,
127 session-bus, ssh-auth. This option can be used multiple times.
128 --device=DEVICE
130 Expose a device to the application. This overrides to the Context
131 section from the application metadata. DEVICE must be one of: dri,
132 kvm, all. This option can be used multiple times.
133 --nodevice=DEVICE
135 Don't expose a device to the application. This overrides to the
136 Context section from the application metadata. DEVICE must be one
137 of: dri, kvm, all. This option can be used multiple times.
138 --allow=FEATURE
140 Allow access to a specific feature. This overrides to the Context
141 section from the application metadata. FEATURE must be one of:
142 devel, multiarch, bluetooth. This option can be used multiple
143 times.
144 See flatpak-build-finish(1) for the meaning of the various
146 features.
147 --disallow=FEATURE
149 Disallow access to a specific feature. This overrides to the
150 Context section from the application metadata. FEATURE must be one
151 of: devel, multiarch, bluetooth. This option can be used multiple
152 times.
153 --filesystem=FS
155 Allow the application access to a subset of the filesystem. This
156 overrides to the Context section from the application metadata. FS
157 can be one of: home, host, xdg-desktop, xdg-documents,
158 xdg-download, xdg-music, xdg-pictures, xdg-public-share,
159 xdg-templates, xdg-videos, xdg-run, xdg-config, xdg-cache,
160 xdg-data, an absolute path, or a homedir-relative path like ~/dir
161 or paths relative to the xdg dirs, like xdg-download/subdir. The
162 optional :ro suffix indicates that the location will be read-only.
163 The optional :create suffix indicates that the location will be
164 read-write and created if it doesn't exist. This option can be used
165 multiple times.
166 --nofilesystem=FILESYSTEM
168 Remove access to the specified subset of the filesystem from the
169 application. This overrides to the Context section from the
170 application metadata. FILESYSTEM can be one of: home, host,
171 xdg-desktop, xdg-documents, xdg-download xdg-music, xdg-pictures,
172 xdg-public-share, xdg-templates, xdg-videos, an absolute path, or a
173 homedir-relative path like ~/dir. This option can be used multiple
174 times.
175 --add-policy=SUBSYSTEM.KEY=VALUE
177 Add generic policy option. For example,
178 "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would
179 map to this metadata:
180 [Policy subsystem]
182 key=v1;v2;
183 This option can be used multiple times.
186 --remove-policy=SUBSYSTEM.KEY=VALUE
188 Remove generic policy option. This option can be used multiple
189 times.
190 --env=VAR=VALUE
192 Set an environment variable in the application. This overrides to
193 the Context section from the application metadata. This option can
194 be used multiple times.
195 --own-name=NAME
197 Allow the application to own the well known name NAME on the
198 session bus. If NAME ends with .*, it allows the application to own
199 all matching names. This overrides to the Context section from the
200 application metadata. This option can be used multiple times.
201 --talk-name=NAME
203 Allow the application to talk to the well known name NAME on the
204 session bus. If NAME ends with .*, it allows the application to
205 talk to all matching names. This overrides to the Context section
206 from the application metadata. This option can be used multiple
207 times.
208 --system-own-name=NAME
210 Allow the application to own the well known name NAME on the system
211 bus. If NAME ends with .*, it allows the application to own all
212 matching names. This overrides to the Context section from the
213 application metadata. This option can be used multiple times.
214 --system-talk-name=NAME
216 Allow the application to talk to the well known name NAME on the
217 system bus. If NAME ends with .*, it allows the application to talk
218 to all matching names. This overrides to the Context section from
219 the application metadata. This option can be used multiple times.
220 --persist=FILENAME
222 If the application doesn't have access to the real homedir, make
223 the (homedir-relative) path FILENAME a bind mount to the
224 corresponding path in the per-application directory, allowing that
225 location to be used for persistent data. This overrides to the
226 Context section from the application metadata. This option can be
227 used multiple times.
228 --log-session-bus
230 Log session bus traffic. This can be useful to see what access you
231 need to allow in your D-Bus policy.
232 --log-system-bus
234 Log system bus traffic. This can be useful to see what access you
235 need to allow in your D-Bus policy.
236 -p, --die-with-parent
238 Kill the entire sandbox when the launching process dies.
239 --file-forwarding
241 If this option is specified, the remaining arguments are scanned,
242 and all arguments that are enclosed between a pair of '@@'
243 arguments are interpreted as file paths, exported in the document
244 store, and passed to the command in the form of the resulting
245 document path. Arguments between '@@u' and '@@' are considered
246 uris, and any file: uris are exported. The exports are
247 non-persistent and with read and write permissions for the
248 application.
249
251 $ flatpak run org.gnome.GEdit
252 $ flatpak run --devel --command=bash org.gnome.Builder
254 $ flatpak run --command=bash org.gnome.Sdk
256
258 flatpak(1), flatpak-override(1), flatpak-enter(1)
259flatpak FLATPAK RUN(1)