FLATPAK-RUN(1)

📦
version 1.18.4 · 17 versions
, in fedora 44, nixpkgs unstable, ubuntu stonking

okay bestie, you just opened FLATPAK RUN, section 1 of the manual. it's the flatpak run page and it is long, so buckle up. we're doing this together. 💖

✨ NAME ✨

flatpak-run — runs an application, or opens a shell in a runtime. that's the whole vibe. that's the assignment. 💅

🦋 SYNOPSIS 🦋

flatpak run [OPTION...] REF [ARG...]

like, that's it. REF and then whatever else you wanna throw at it. simple. iconic. ✨

🌸 DESCRIPTION 🌸

so here's the tea, bestie. if REF names an installed application, Flatpak runs that app inside a sandboxed environment. any extra arguments you tack on get passed straight through to the application. 💫

the app's current branch and arch get used, unless you say otherwise with --branch or --arch. also go peek at flatpak-make-current(1) if you're curious. 👀

if REF names a runtime instead, then a shell gets opened inside the runtime. super handy for development and testing, ngl. if there's any ambiguity about which branch to use, you'll get prompted to choose — so use --branch to skip that whole conversation. and the primary arch gets used unless you specify otherwise with --arch. 🐚

by default, Flatpak looks for the application or runtime in the per-user installation first, and then in all system installations. wanna override that? you got --user, --system and --installation. pick your fighter. 🥊

🎀 the sandbox, explained 🎀

Flatpak creates a sandboxed environment for the app to run in, and it does that by:

  • mounting the right runtime at /usr
  • mounting a writable directory at /var, whose contents are preserved between application runs
  • mounting the application itself at /app

the deets of that sandboxed environment are controlled by the application metadata and by various options you pass to the run command, like --share and --socket. access is allowed if it was requested either in the application metadata file or with an option — and the user hasn't overridden it. no sneaking, no surprises. 🕵️

the remaining arguments get passed to the command that actually runs in the sandboxed environment. and if you're doing file stuff, go read up on the --file-forwarding option, it handles file arguments for you. 📂

💜 environment variables, aka the drama 💜

environment variables are generally passed on to the sandboxed application, with certain exceptions — as long as --clear-env is not specified. the application metadata can override environment variables, and so can the --env option. 💅

apart from all that, Flatpak always unsets or overrides the following variables, because their session values are likely to interfere with the functioning of the sandbox:

PATH
LD_LIBRARY_PATH
LD_PRELOAD
LD_AUDIT
XDG_CONFIG_DIRS
XDG_DATA_DIRS
SHELL
TEMP
TEMPDIR
TMP
TMPDIR
XDG_RUNTIME_DIR
container
TZDIR
PYTHONPATH
PYTHONPYCACHEPREFIX
PERLLIB
PERL5LIB
XCURSOR_PATH
GST_PLUGIN_PATH_1_0
GST_REGISTRY
GST_REGISTRY_1_0
GST_PLUGIN_PATH
GST_PLUGIN_SYSTEM_PATH
GST_PLUGIN_SCANNER
GST_PLUGIN_SCANNER_1_0
GST_PLUGIN_SYSTEM_PATH_1_0
GST_PRESET_PATH
GST_PTP_HELPER
GST_PTP_HELPER_1_0
GST_INSTALL_PLUGINS_HELPER
KRB5CCNAME
XKB_CONFIG_ROOT
GIO_EXTRA_MODULES
GDK_BACKEND
VK_ADD_DRIVER_FILES
VK_ADD_LAYER_PATH
VK_DRIVER_FILES
VK_ICD_FILENAMES
VK_LAYER_PATH
__EGL_EXTERNAL_PLATFORM_CONFIG_DIRS
__EGL_EXTERNAL_PLATFORM_CONFIG_FILENAMES
__EGL_VENDOR_LIBRARY_DIRS
__EGL_VENDOR_LIBRARY_FILENAMES

also? several environment variables with the prefix GST_ that gstreamer uses get unset too. since Flatpak 1.12.5. so don't come for me about your gstreamer plugins. 😭

🌈 the XDG glow-up 🌈

Flatpak also overrides the XDG environment variables so sandboxed applications get pointed at their writable filesystem locations under ~/.var/app/$APPID/:

XDG_DATA_HOME
XDG_CONFIG_HOME
XDG_CACHE_HOME
XDG_STATE_HOME (since Flatpak 1.13)

apps can use the --persist=.local/state and --unset-env=XDG_STATE_HOME options to get a Flatpak 1.13-compatible ~/.local/state on older versions of Flatpak. so you're not left out if you're on an older build, periodt. 🫶

the host values of these variables are made available inside the sandbox through these HOST_-prefixed variables:

HOST_XDG_DATA_HOME
HOST_XDG_CONFIG_HOME
HOST_XDG_CACHE_HOME
HOST_XDG_STATE_HOME (since Flatpak 1.13)

🧚 a few more iconic facts 🧚

Flatpak sets the environment variable FLATPAK_ID to the application ID of the running app. so the app always knows who it is. main character energy, honestly. 👑

Flatpak also bind-mounts, read-only, the host's /etc/os-release (or /usr/lib/os-release as a fallback, if the first one isn't available) to /run/host/os-release, in accordance with the os-release specification[1]. ⭐

and if parental controls support is enabled, flatpak will check the current user's parental controls settings, and will refuse to run an app if it is blocklisted for the current user. nope. not today. 🙈

💅 OPTIONS 💅

here are all the options you can understand, bestie. all of them. we're not skipping a single one. ✨

  • -h, --help — show the help options and dip out. 👋
  • -u, --user — look for the application and runtime in per-user installations.
  • --system — look for the application and runtime in the default system-wide installations.
  • --installation=NAME — look for the application and runtime in the system-wide installation named by NAME, chosen from the ones defined in /etc/flatpak/installations.d/. btw, using --installation=default is equivalent to using --system. 🎯
  • -v, --verbose — print debug information while the command is being processed. the receipts, basically. 🧾
  • --ostree-verbose — print OSTree debug information while the command is being processed. even more receipts. 🔍
  • --arch=ARCH — the architecture to run. peep flatpak --supported-arches for the architectures your host supports. 🏗️
  • --command=COMMAND — the command to run instead of the one listed in the application metadata. 💫
  • --cwd=DIR — the directory to run the command in. heads up though: this has to be a directory inside the sandbox. 🏠
  • --branch=BRANCH — the branch to use. 🌿
  • -d, --devel — use the devel runtime that's specified in the application metadata instead of the regular runtime, and use a seccomp profile that is less likely to break development tools. devs, this one's for you. 🔥
  • --runtime=RUNTIME — use this runtime instead of the one 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 too. any empty or missing parts get filled in with the corresponding values specified by the app. 🧩
  • --runtime-version=VERSION — use this version of the runtime instead of the one specified in the application metadata. this overrides any version specified with the --runtime option. so it wins. periodt. 👑
  • --share=SUBSYSTEM — share a subsystem with the host session. this overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. you can use this option multiple times. 🫱
  • --unshare=SUBSYSTEM — don't share a subsystem with the host session. this overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. you can use this option multiple times. 🚫
  • --share-if=SUBSYSTEM:CONDITION — share a subsystem with the host session conditionally, only when the specified condition is met at runtime. this overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. conditions can be negated with !, for example !has-input-device. you can use this option multiple times. available since 1.17. 🌈

see the Conditional Permissions section in flatpak-metadata(5) for more details. 📖

  • --socket=SOCKET — expose a well known socket to the application. this overrides 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, inherit-wayland-socket. you can use this option multiple times. 🔌
  • --nosocket=SOCKET — don't expose a well known socket to the application. this overrides 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, inherit-wayland-socket. you can use this option multiple times. 🙅
  • --socket-if=SOCKET:CONDITION — expose a well-known socket to the application conditionally, only when the specified condition is met at runtime. this overrides 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, inherit-wayland-socket. CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. conditions can be negated with !, for example !has-wayland. you can use this option multiple times. available since 1.17. ✨

see the Conditional Permissions section in flatpak-metadata(5) for more details. 📖

  • --device=DEVICE — expose a device to the application. this overrides the Context section from the application metadata. DEVICE must be one of: dri, input, usb, kvm, shm, all. you can use this option multiple times. 🖨️
  • --nodevice=DEVICE — don't expose a device to the application. this overrides the Context section from the application metadata. DEVICE must be one of: dri, input, usb, kvm, shm, all. you can use this option multiple times. 🚫
  • --device-if=DEVICE:CONDITION — expose a device to the application conditionally, only when the specified condition is met at runtime. this overrides the Context section from the application metadata. DEVICE must be one of: dri, input, usb, kvm, shm, all. CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. conditions can be negated with !, for example !has-input-device. you can use this option multiple times. available since 1.17. 💖

see the Conditional Permissions section in flatpak-metadata(5) for more details. 📖

  • --allow=FEATURE — allow access to a specific feature. this overrides the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. you can use this option multiple times. ✅

see flatpak-build-finish(1) for the meaning of the various features. 🔍

  • --disallow=FEATURE — disallow access to a specific feature. this overrides the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. you can use this option multiple times. ❌
  • --allow-if=FEATURE:CONDITION — bestie this one is conditional access, the pickiest of permissions 💅 It lets the app get at a specific feature, but only when the condition you name is actually true at runtime. It overrides the Context section from the application metadata. FEATURE has to be one of: devel, multiarch, bluetooth. CONDITION has to be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. You can negate a condition with !, like !has-input-device — literally the "not" of it all. This option can be used multiple times. Available since 1.17. ✨

For the whole lore on this, go read the Conditional Permissions section in flatpak-metadata(5), no cap.

  • --filesystem=FILESYSTEM — okay so this hands the app a slice of the filesystem. It overrides the Context section from the application metadata. FILESYSTEM can be one of: home, host, host-os, host-etc, host-root, 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 means read-only, don't even think about writing. The optional :create suffix means read-write and it gets created if it's not there yet. This option can be used multiple times. For what all these filesystems actually mean, check the "[Context] filesystems" list in flatpak-metadata(5). 🫶
  • --nofilesystem=FILESYSTEM — the undo button 🎀 This reverses the effect of a previous --filesystem=FILESYSTEM in the app's manifest and/or the overrides you set up with flatpak-override(1). It overrides the Context section of the application metadata. FILESYSTEM takes the same values as for --filesystem, but heads up: the :ro and :create suffixes are not used here. This option can be used multiple times.
Important, listen up: this does not block access to a more narrowly-scoped --filesystem. Say an app has the equivalent of --filesystem=xdg-config/MyApp in its manifest or as a system-wide override, and then flatpak override --user --nofilesystem=home as a per-user override — it gets blocked from most of the home directory, yes, but it can still get into $XDG_CONFIG_HOME/MyApp. Sneaky, but that's how it is. 😭

And as a special case, --nofilesystem=host:reset ignores all --filesystem permissions inherited from the app manifest or flatpak-override(1), plus it does the same thing as --nofilesystem=host. Double whammy. 💥

  • --add-policy=SUBSYSTEM.KEY=VALUE — adds a generic policy option. For example, "--add-policy=subsystem.key=v1 --add-policy=subsystem.key=v2" would map to this metadata:
[Policy subsystem]
key=v1;v2;

This option can be used multiple times.

  • --remove-policy=SUBSYSTEM.KEY=VALUE — removes a generic policy option. This option can be used multiple times. Bye bye policy 👋
  • --usb=TYPE[:DATA] — adds a USB device query to the application metadata, which lets the USB portal enumerate and use the device. TYPE must be one of: all, cls, dev, vnd. Let's break it down 🔍
    • all — matches all devices. all of them. every last one. 💀
    • cls — a device class and subclass query. DATA must be in the form CLASS:SUBCLASS where both CLASS and SUBCLASS must be a valid 2-digit hexadecimal class id number. Alternatively, SUBCLASS may be * to match all subclasses.
    • dev — a device product id query. DATA must be a valid 4-digit hexadecimal product id number, for example 0a1b. It requires a vnd filter in the query.
    • vnd — a device vendor id query. DATA must be a valid 4-digit hexadecimal vendor id number greater than zero, for example 0fab.

You can compose multiple device queries together with the + sign, for example --usb=vnd:0123+dev:4567. The dev filter requires a vnd. Available since 1.15.11. 🌈

  • --nousb=VENDOR_ID:PRODUCT_ID — adds a blocking USB device query to the application metadata. Blocked devices take precedence over allowed devices — so yeah, the block wins, always. The syntax is exactly equal to --usb. Available since 1.15.11.
  • --env=VAR=VALUE — sets an environment variable in the application. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --unset-env=VAR — unsets 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.
  • --env-fd=FD — reads environment variables from the file descriptor FD, and sets them as if via --env. Iconic for when you don't want environment variables and their values being visible to other users. 🤫

Each environment variable is in the form VAR=VALUE followed by a zero byte. This is the same format used by env -0 and /proc/*/environ.

  • --clear-env — does not pass environment variables from the outside into the sandboxed application. Explicitly set and unset environment variables still get applied though. So the ones you asked for stay. 💅
  • --own-name=NAME — lets the application own the well known name NAME on the session bus. If NAME ends with .*, it lets the app own all matching names. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --talk-name=NAME — lets the application talk to the well known name NAME on the session bus. If NAME ends with .*, it lets the app talk to all matching names. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --no-talk-name=NAME — doesn't 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 the Context section from the application metadata. This option can be used multiple times.
  • --system-own-name=NAME — lets the application own the well known name NAME on the system bus. If NAME ends with .*, it lets the app own all matching names. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --system-talk-name=NAME — lets the application talk to the well known name NAME on the system bus. If NAME ends with .*, it lets the app talk to all matching names. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --system-no-talk-name=NAME — doesn't 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 the Context section from the application metadata. This option can be used multiple times.
  • --a11y-own-name=NAME — lets the application own the well known name NAME on the a11y bus. If NAME ends with .*, it lets the app own all matching names. This overrides the Context section from the application metadata. This option can be used multiple times.
  • --persist=FILENAME — if the app doesn't have access to the real homedir, this makes the (homedir-relative) path FILENAME a bind mount to the corresponding path in the per-application directory, so that location can be used for persistent data. This overrides the Context section from the application metadata. This option can be used multiple times. 🦋
  • --no-session-bus — runs this instance without the filtered access to the session dbus connection. Note: this is the default when run with --sandbox.
  • --session-bus — allows filtered access to the session dbus connection. This is the default, except when run with --sandbox.
Sandbox mode lore: even if you allow access to the session bus, the sandbox can't talk to or own the application ids (org.the.App.*) on the bus — unless they're explicitly added — only names in the .Sandboxed subset (org.the.App.Sandboxed.* and org.mpris.MediaPlayer2.org.the.App.Sandboxed.*). Periodt.
  • --no-a11y-bus — runs this instance without access to the accessibility bus. Note: this is the default when run with --sandbox.
  • --a11y-bus — allows access to the accessibility bus. This is the default, except when run with --sandbox.
  • --sandbox — runs the application in sandboxed mode, which means dropping all the extra permissions it would otherwise have, plus access to the session/system/a11y buses and document portal. It's giving ✨full lockdown✨.
  • --log-session-bus — logs session bus traffic. Genuinely so useful for seeing what access you need to allow in your D-Bus policy. 👑
  • --log-system-bus — logs system bus traffic. Also so useful for seeing what access you need to allow in your D-Bus policy.
  • -p, --die-with-parent — kills the entire sandbox when the launching process dies. Dramatic but necessary. 💀
  • --parent-pid=PID — specifies the pid of the "parent" flatpak, used by --parent-expose-pids and --parent-share-pids.
  • --parent-expose-pids — makes the processes of the new sandbox visible in the sandbox of the parent flatpak, as defined by --parent-pid.
  • --parent-share-pids — uses 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.
  • --instance-id-fd — writes the instance ID string to the given file descriptor.
  • --file-forwarding — if this option is specified, the remaining arguments are scanned, and all arguments enclosed between a pair of @@ 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 "@@u" and "@@" are considered URIs, and any "file:" URIs are exported. The exports are non-persistent and with read and write permissions for the application. 🎀
  • --app-path=PATH — instead of mounting the app's content on /app in the sandbox, mount PATH on /app, and the app's 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 LD_LIBRARY_PATH inside the sandbox.
  • --app-path= — as a special case, --app-path= (with an empty PATH) results in an empty directory being mounted on /app. Empty. Nothing. Void. 🙈
  • --usr-path=PATH — okay so instead of mounting the runtime's files on /usr inside the sandbox, you mount PATH on /usr and the runtime's normal files get yeeted over to /run/parent/usr. And if the runtime has extensions? Those get redirected into /run/parent/usr too, and ngl they will not be in the LD_LIBRARY_PATH inside the sandbox. 🙈
real talk: this one's basically only useful if you pair it up with --app-path= and --env=LD_LIBRARY_PATH=.... Like, it's giving very "situationship with two other flags" energy. 💅

✨ EXAMPLES ✨

Okay bestie, here's the vibe in action 🎀

$ flatpak run org.gnome.gedit
$ flatpak run --devel --command=bash org.gnome.Builder
$ flatpak run --command=bash org.gnome.Sdk
$ flatpak run org.gnome.Boxes --nousb=0fd9:*

See? Look at those. Chef's kiss. 👑 Notice how the app arguments just come along for the ride at the end — --nousb=0fd9:* there is being passed to the app itself, not to flatpak run. That's the whole point. 🦋

🌈 SEE ALSO 🌈

Your little squad of related pages, go read them fr fr:

💜 NOTES 💜

  1. os-release specification
https://www.freedesktop.org/software/systemd/man/os-release.html

And that's a wrap on the whole page, bestie!! 🎀✨ This is the flatpak manual — page FLATPAK RUN(1) — so if you ever forget which page you're on, it's literally right there in the footer, giving main character energy at the bottom of the screen. 💖 Go run something cute. 🧚

📦 where this page comes from