'\" t
.\"     Title: flatpak run
.\"    Author: Alexander Larsson <alexl@redhat.com>
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 03/16/2023
.\"    Manual: flatpak run
.\"    Source: flatpak
.\"  Language: English
.\"
.TH "FLATPAK RUN" "1" "" "flatpak" "flatpak run"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
flatpak-run \- Run an application or open a shell in a runtime
.SH "SYNOPSIS"
.HP \w'\fBflatpak\ run\fR\ 'u
\fBflatpak run\fR [OPTION...] REF [ARG...]
.SH "DESCRIPTION"
.PP
If
REF
names an installed application, Flatpak runs the application in a sandboxed environment\&. Extra arguments are passed on to the application\&. The current branch and arch of the application is used unless otherwise specified with
\fB\-\-branch\fR
or
\fB\-\-arch\fR\&. See
\fBflatpak-make-current\fR(1)\&.
.PP
If
REF
names a runtime, a shell is opened in the runtime\&. This is useful for development and testing\&. If there is ambiguity about which branch to use, you will be prompted to choose\&. Use
\fB\-\-branch\fR
to avoid this\&. The primary arch is used unless otherwise specified with
\fB\-\-arch\fR\&.
.PP
By default, Flatpak will look for the application or runtime in the per\-user installation first, then in all system installations\&. This can be overridden with the
\fB\-\-user\fR,
\fB\-\-system\fR
and
\fB\-\-installation\fR
options\&.
.PP
Flatpak creates a sandboxed environment for the application to run in by mounting the right runtime at
/usr
and a writable directory at
/var, whose content is preserved between application runs\&. The application itself is mounted at
/app\&.
.PP
The details of the sandboxed environment are controlled by the application metadata and various options like
\fB\-\-share\fR
and
\fB\-\-socket\fR
that are passed to the run command: Access is allowed if it was requested either in the application metadata file or with an option and the user hasn\*(Aqt overridden it\&.
.PP
The remaining arguments are passed to the command that gets run in the sandboxed environment\&. See the
\fB\-\-file\-forwarding\fR
option for handling of file arguments\&.
.PP
Environment variables are generally passed on to the sandboxed application, with certain exceptions\&. The application metadata can override environment variables, as well as the
\fB\-\-env\fR
option\&. Apart from that, Flatpak always unsets or overrides the following variables, since their session values are likely to interfere with the functioning of the sandbox:
.RS 4
PATH
.RE
.RS 4
LD_LIBRARY_PATH
.RE
.RS 4
XDG_CONFIG_DIRS
.RE
.RS 4
XDG_DATA_DIRS
.RE
.RS 4
XDG_RUNTIME_DIR
.RE
.RS 4
SHELL
.RE
.RS 4
TEMP
.RE
.RS 4
TEMPDIR
.RE
.RS 4
TMP
.RE
.RS 4
TMPDIR
.RE
.RS 4
PYTHONPATH
.RE
.RS 4
PERLLIB
.RE
.RS 4
PERL5LIB
.RE
.RS 4
XCURSOR_PATH
.RE
.RS 4
KRB5CCNAME
.RE
.RS 4
XKB_CONFIG_ROOT
.RE
.RS 4
GIO_EXTRA_MODULES
.RE
.RS 4
GDK_BACKEND
.RE
.PP
Also several environment variables with the prefix "GST_" that are used by gstreamer are unset (since Flatpak 1\&.12\&.5)\&.
.PP
Flatpak also overrides the XDG environment variables to point sandboxed applications at their writable filesystem locations below
~/\&.var/app/$APPID/:
.RS 4
XDG_DATA_HOME
.RE
.RS 4
XDG_CONFIG_HOME
.RE
.RS 4
XDG_CACHE_HOME
.RE
.RS 4
XDG_STATE_HOME (since Flatpak 1\&.13)
.RE
.PP
Apps can use the
\fB\-\-persist=\&.local/state\fR
and
\fB\-\-unset\-env=XDG_STATE_HOME\fR
options to get a Flatpak 1\&.13\-compatible
~/\&.local/state
on older versions of Flatpak\&.
.PP
The host values of these variables are made available inside the sandbox via these HOST_\-prefixed variables:
.RS 4
HOST_XDG_DATA_HOME
.RE
.RS 4
HOST_XDG_CONFIG_HOME
.RE
.RS 4
HOST_XDG_CACHE_HOME
.RE
.RS 4
HOST_XDG_STATE_HOME (since Flatpak 1\&.13)
.RE
.PP
Flatpak sets the environment variable
\fBFLATPAK_ID\fR
to the application ID of the running app\&.
.PP
Flatpak also bind\-mounts as read\-only the host\*(Aqs
/etc/os\-release
(if available, or
/usr/lib/os\-release
as a fallback) to
/run/host/os\-release
in accordance with the
\m[blue]\fBos\-release specification\fR\m[]\&\s-2\u[1]\d\s+2\&.
.PP
If parental controls support is enabled, flatpak will check the current user\(cqs parental controls settings, and will refuse to run an app if it is blocklisted for the current user\&.
.SH "OPTIONS"
.PP
The following options are understood:
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show help options and exit\&.
.RE
.PP
\fB\-u\fR, \fB\-\-user\fR
.RS 4
Look for the application and runtime in per\-user installations\&.
.RE
.PP
\fB\-\-system\fR
.RS 4
Look for the application and runtime in the default system\-wide installations\&.
.RE
.PP
\fB\-\-installation=NAME\fR
.RS 4
Look for the application and runtime in the system\-wide installation specified by
NAME
among those defined in
/etc/flatpak/installations\&.d/\&. Using
\fB\-\-installation=default\fR
is equivalent to using
\fB\-\-system\fR\&.
.RE
.PP
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Print debug information during command processing\&.
.RE
.PP
\fB\-\-ostree\-verbose\fR
.RS 4
Print OSTree debug information during command processing\&.
.RE
.PP
\fB\-\-arch=ARCH\fR
.RS 4
The architecture to run\&. See
\fBflatpak \-\-supported\-arches\fR
for architectures supported by the host\&.
.RE
.PP
\fB\-\-command=COMMAND\fR
.RS 4
The command to run instead of the one listed in the application metadata\&.
.RE
.PP
\fB\-\-cwd=DIR\fR
.RS 4
The directory to run the command in\&. Note that this must be a directory inside the sandbox\&.
.RE
.PP
\fB\-\-branch=BRANCH\fR
.RS 4
The branch to use\&.
.RE
.PP
\fB\-d\fR, \fB\-\-devel\fR
.RS 4
Use the devel runtime that is specified in the application metadata instead of the regular runtime, and use a seccomp profile that is less likely to break development tools\&.
.RE
.PP
\fB\-\-runtime=RUNTIME\fR
.RS 4
Use this runtime instead of the one that is specified in the application metadata\&. This is a full tuple, like for example
org\&.freedesktop\&.Sdk/x86_64/1\&.2, but partial tuples are allowed\&. Any empty or missing parts are filled in with the corresponding values specified by the app\&.
.RE
.PP
\fB\-\-runtime\-version=VERSION\fR
.RS 4
Use this version of the runtime instead of the one that is specified in the application metadata\&. This overrides any version specified with the \-\-runtime option\&.
.RE
.PP
\fB\-\-share=SUBSYSTEM\fR
.RS 4
Share a subsystem with the host session\&. This overrides the Context section from the application metadata\&.
SUBSYSTEM
must be one of: network, ipc\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-unshare=SUBSYSTEM\fR
.RS 4
Don\*(Aqt share a subsystem with the host session\&. This overrides the Context section from the application metadata\&.
SUBSYSTEM
must be one of: network, ipc\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-socket=SOCKET\fR
.RS 4
Expose a well known socket to the application\&. This overrides to the Context section from the application metadata\&.
SOCKET
must be one of: x11, wayland, fallback\-x11, pulseaudio, system\-bus, session\-bus, ssh\-auth, pcsc, cups, gpg\-agent\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-nosocket=SOCKET\fR
.RS 4
Don\*(Aqt expose a well known socket to the application\&. This overrides to the Context section from the application metadata\&.
SOCKET
must be one of: x11, wayland, fallback\-x11, pulseaudio, system\-bus, session\-bus, ssh\-auth, pcsc, cups, gpg\-agent\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-device=DEVICE\fR
.RS 4
Expose a device to the application\&. This overrides to the Context section from the application metadata\&.
DEVICE
must be one of: dri, kvm, shm, all\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-nodevice=DEVICE\fR
.RS 4
Don\*(Aqt expose a device to the application\&. This overrides to the Context section from the application metadata\&.
DEVICE
must be one of: dri, kvm, shm, all\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-allow=FEATURE\fR
.RS 4
Allow access to a specific feature\&. This overrides to the Context section from the application metadata\&.
FEATURE
must be one of: devel, multiarch, bluetooth\&. This option can be used multiple times\&.
.sp
See
\fBflatpak-build-finish\fR(1)
for the meaning of the various features\&.
.RE
.PP
\fB\-\-disallow=FEATURE\fR
.RS 4
Disallow access to a specific feature\&. This overrides to the Context section from the application metadata\&.
FEATURE
must be one of: devel, multiarch, bluetooth\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-filesystem=FILESYSTEM\fR
.RS 4
Allow the application access to a subset of the filesystem\&. This overrides to the Context section from the application metadata\&.
FILESYSTEM
can be one of: home, host, host\-os, host\-etc, xdg\-desktop, xdg\-documents, xdg\-download, xdg\-music, xdg\-pictures, xdg\-public\-share, xdg\-templates, xdg\-videos, xdg\-run, xdg\-config, xdg\-cache, xdg\-data, an absolute path, or a homedir\-relative path like ~/dir or paths relative to the xdg dirs, like xdg\-download/subdir\&. The optional :ro suffix indicates that the location will be read\-only\&. The optional :create suffix indicates that the location will be read\-write and created if it doesn\*(Aqt exist\&. This option can be used multiple times\&. See the "[Context] filesystems" list in
\fBflatpak-metadata\fR(5)
for details of the meanings of these filesystems\&.
.RE
.PP
\fB\-\-nofilesystem=FILESYSTEM\fR
.RS 4
Undo the effect of a previous
\fB\-\-filesystem=\fRFILESYSTEM
in the app\*(Aqs manifest and/or the overrides set up with
\fBflatpak-override\fR(1)\&. This overrides the Context section of the application metadata\&.
FILESYSTEM
can take the same values as for
\fB\-\-filesystem\fR, but the
:ro
and
:create
suffixes are not used here\&. This option can be used multiple times\&.
.sp
This option does not prevent access to a more narrowly\-scoped
\fB\-\-filesystem\fR\&. For example, if an application has the equivalent of
\fB\-\-filesystem=xdg\-config/MyApp\fR
in its manifest or as a system\-wide override, and
flatpak override \-\-user \-\-nofilesystem=home
as a per\-user override, then it will be prevented from accessing most of the home directory, but it will still be allowed to access
$XDG_CONFIG_HOME/MyApp\&.
.sp
As a special case,
\fB\-\-nofilesystem=host:reset\fR
will ignore all
\fB\-\-filesystem\fR
permissions inherited from the app manifest or
\fBflatpak-override\fR(1), in addition to having the behaviour of
\fB\-\-nofilesystem=host\fR\&.
.RE
.PP
\fB\-\-add\-policy=SUBSYSTEM\&.KEY=VALUE\fR
.RS 4
Add generic policy option\&. For example, "\-\-add\-policy=subsystem\&.key=v1 \-\-add\-policy=subsystem\&.key=v2" would map to this metadata:
.sp
.if n \{\
.RS 4
.\}
.nf
[Policy subsystem]
key=v1;v2;
.fi
.if n \{\
.RE
.\}
.sp

This option can be used multiple times\&.
.RE
.PP
\fB\-\-remove\-policy=SUBSYSTEM\&.KEY=VALUE\fR
.RS 4
Remove generic policy option\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-env=VAR=VALUE\fR
.RS 4
Set an environment variable in the application\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-unset\-env=VAR\fR
.RS 4
Unset an environment variable in the application\&. This overrides the unset\-environment entry in the [Context] group of the metadata, and the [Environment] group\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-env\-fd=\fR\fB\fIFD\fR\fR
.RS 4
Read environment variables from the file descriptor
\fIFD\fR, and set them as if via
\fB\-\-env\fR\&. This can be used to avoid environment variables and their values becoming visible to other users\&.
.sp
Each environment variable is in the form
\fIVAR\fR=\fIVALUE\fR
followed by a zero byte\&. This is the same format used by
env \-0
and
/proc/*/environ\&.
.RE
.PP
\fB\-\-own\-name=NAME\fR
.RS 4
Allow the application to own the well known name
NAME
on the session bus\&. If
NAME
ends with \&.*, it allows the application to own all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-talk\-name=NAME\fR
.RS 4
Allow the application to talk to the well known name
NAME
on the session bus\&. If
NAME
ends with \&.*, it allows the application to talk to all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-no\-talk\-name=NAME\fR
.RS 4
Don\*(Aqt allow the application to talk to the well known name
NAME
on the session bus\&. If
NAME
ends with \&.*, it allows the application to talk to all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-system\-own\-name=NAME\fR
.RS 4
Allow the application to own the well known name
NAME
on the system bus\&. If
NAME
ends with \&.*, it allows the application to own all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-system\-talk\-name=NAME\fR
.RS 4
Allow the application to talk to the well known name
NAME
on the system bus\&. If
NAME
ends with \&.*, it allows the application to talk to all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-system\-no\-talk\-name=NAME\fR
.RS 4
Don\*(Aqt allow the application to talk to the well known name
NAME
on the system bus\&. If
NAME
ends with \&.*, it allows the application to talk to all matching names\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-persist=FILENAME\fR
.RS 4
If the application doesn\*(Aqt have access to the real homedir, make the (homedir\-relative) path
FILENAME
a bind mount to the corresponding path in the per\-application directory, allowing that location to be used for persistent data\&. This overrides to the Context section from the application metadata\&. This option can be used multiple times\&.
.RE
.PP
\fB\-\-no\-session\-bus\fR
.RS 4
Run this instance without the filtered access to the session dbus connection\&. Note, this is the default when run with \-\-sandbox\&.
.RE
.PP
\fB\-\-session\-bus\fR
.RS 4
Allow filtered access to the session dbus connection\&. This is the default, except when run with \-\-sandbox\&.
.sp
In sandbox mode, even if you allow access to the session bus the sandbox cannot talk to or own the application ids (org\&.the\&.App\&.*) on the bus (unless explicitly added), only names in the \&.Sandboxed subset (org\&.the\&.App\&.Sandboxed\&.* and org\&.mpris\&.MediaPlayer2\&.org\&.the\&.App\&.Sandboxed\&.*)\&.
.RE
.PP
\fB\-\-no\-a11y\-bus\fR
.RS 4
Run this instance without the access to the accessibility bus\&. Note, this is the default when run with \-\-sandbox\&.
.RE
.PP
\fB\-\-a11y\-bus\fR
.RS 4
Allow access to the accessibility bus\&. This is the default, except when run with \-\-sandbox\&.
.RE
.PP
\fB\-\-sandbox\fR
.RS 4
Run the application in sandboxed mode, which means dropping all the extra permissions it would otherwise have, as well as access to the session/system/a11y busses and document portal\&.
.RE
.PP
\fB\-\-log\-session\-bus\fR
.RS 4
Log session bus traffic\&. This can be useful to see what access you need to allow in your D\-Bus policy\&.
.RE
.PP
\fB\-\-log\-system\-bus\fR
.RS 4
Log system bus traffic\&. This can be useful to see what access you need to allow in your D\-Bus policy\&.
.RE
.PP
\fB\-p\fR, \fB\-\-die\-with\-parent\fR
.RS 4
Kill the entire sandbox when the launching process dies\&.
.RE
.PP
\fB\-\-parent\-pid=PID\fR
.RS 4
Specifies the pid of the "parent" flatpak, used by \-\-parent\-expose\-pids and \-\-parent\-share\-pids\&.
.RE
.PP
\fB\-\-parent\-expose\-pids\fR
.RS 4
Make the processes of the new sandbox visible in the sandbox of the parent flatpak, as defined by \-\-parent\-pid\&.
.RE
.PP
\fB\-\-parent\-share\-pids\fR
.RS 4
Use the same process ID namespace for the processes of the new sandbox and the sandbox of the parent flatpak, as defined by \-\-parent\-pid\&. Implies \-\-parent\-expose\-pids\&.
.RE
.PP
\fB\-\-instance\-id\-fd\fR
.RS 4
Write the instance ID string to the given file descriptor\&.
.RE
.PP
\fB\-\-file\-forwarding\fR
.RS 4
If this option is specified, the remaining arguments are scanned, and all arguments that are enclosed between a pair of \*(Aq@@\*(Aq arguments are interpreted as file paths, exported in the document store, and passed to the command in the form of the resulting document path\&. Arguments between \*(Aq@@u\*(Aq and \*(Aq@@\*(Aq are considered uris, and any file: uris are exported\&. The exports are non\-persistent and with read and write permissions for the application\&.
.RE
.PP
\fB\-\-app\-path=\fR\fB\fIPATH\fR\fR
.RS 4
Instead of mounting the app\*(Aqs content on
/app
in the sandbox, mount
\fIPATH\fR
on
/app, and the app\*(Aqs content on
/run/parent/app\&. If the app has extensions, they will also be redirected into
/run/parent/app, and will not be included in the
\fBLD_LIBRARY_PATH\fR
inside the sandbox\&.
.RE
.PP
\fB\-\-app\-path=\fR
.RS 4
As a special case,
\fB\-\-app\-path=\fR
(with an empty
\fIPATH\fR) results in an empty directory being mounted on
/app\&.
.RE
.PP
\fB\-\-usr\-path=\fR\fB\fIPATH\fR\fR
.RS 4
Instead of mounting the runtime\*(Aqs files on
/usr
in the sandbox, mount
\fIPATH\fR
on
/usr, and the runtime\*(Aqs normal files on
/run/parent/usr\&. If the runtime has extensions, they will also be redirected into
/run/parent/usr, and will not be included in the
\fBLD_LIBRARY_PATH\fR
inside the sandbox\&.
This option will usually only be useful if it is combined with
\fB\-\-app\-path=\fR
and
\fB\-\-env=LD_LIBRARY_PATH=\fR\fB\fI\&.\&.\&.\fR\fR\&.
.RE
.SH "EXAMPLES"
.PP
\fB$ flatpak run org\&.gnome\&.gedit\fR
.PP
\fB$ flatpak run \-\-devel \-\-command=bash org\&.gnome\&.Builder\fR
.PP
\fB$ flatpak run \-\-command=bash org\&.gnome\&.Sdk\fR
.SH "SEE ALSO"
.PP
\fBflatpak\fR(1),
\fBflatpak-override\fR(1),
\fBflatpak-enter\fR(1)
.SH "NOTES"
.IP " 1." 4
os-release specification
.RS 4
\%https://www.freedesktop.org/software/systemd/man/os-release.html
.RE