FLATPAK-OVERRIDE(1)

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

💖 FLATPAK-OVERRIDE 💖

okay bestie, pull up a chair 🪑 because we're talking about flatpak-override — that's section 1 of the manual, the main character of the flatpak override saga 👑

✨ NAME ✨

flatpak-override — Override application requirements 🎀

🦋 SYNOPSIS 🦋

flatpak override [OPTION...] [APP]

🌸 DESCRIPTION 🌸

so basically? it overrides the application's specified runtime requirements. 💅 Which is the fancy way of saying: this is how you hand a sandboxed app more or less stuff than it asked for. Give it the goods, or take the goods away. Your call, your rules, your sandbox 🏖️

By default, the app gets access to the resources it requested when it's started. That's the "trust the app, it knows what it wants" default. But you — yes you, the icon you are 👑 — can override that:

  • On a particular instance — by passing extra arguments to flatpak run. One-off vibe, just for that run.
  • Every single time — by using flatpak override. Permanent, set-it-and-forget-it energy ✨

The application overrides get saved in text files that live in $XDG_DATA_HOME/flatpak/overrides in user mode 📁 (yes, literally text files, you can go look at them, they're not hiding anything, we love transparency 💖).

If the application ID APP is not specified, then the overrides affect all applications 🌈 — global queen behaviour. But (plot twist 🫢) the per-application overrides can override the global overrides. So the specific app always wins the argument. Periodt 💅

⚠️ Heads up bestie: unless you override it with the --user or --installation options, this command changes the default system-wide installation. So like, it's not just you — it's everybody. Act accordingly 😭

more coming, don't go anywhere 🫶

✨ OPTIONS ✨

okay so here's the whole menu of things you can pass. all of these are understood by the command, bestie 💖

  • -h, --help — shows you the help options and dips. that's it, that's the whole job 🫶
  • -u, --user — updates a per-user installation. your own little corner of the world, just for you 💜
  • --system — updates the default system-wide installation. the big shared one, everybody's business 🌈
  • --installation=NAME — updates a system-wide installation, picked by NAME, from the ones defined in /etc/flatpak/installations.d/. and heads up: using --installation=default is literally the same thing as using --system, no cap 👑
  • --share=SUBSYSTEM — shares a subsystem with the host session. this overrides the Context section from the application metadata. SUBSYSTEM has to be one of: network, ipc. you can use this option multiple times, stack 'em up ✨
  • --unshare=SUBSYSTEM — the opposite vibe: does NOT share a subsystem with the host session. this overrides the Context section from the application metadata. SUBSYSTEM must be one of: network, ipc. also usable multiple times 💅
  • --share-if=SUBSYSTEM:CONDITION — shares a subsystem with the host session conditionally, only when the specified condition is actually 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 !, like !has-input-device. multiple uses allowed. available since 1.17 🦋

see the Conditional Permissions section in flatpak-metadata(5) for the whole tea.

  • --socket=SOCKET — exposes 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. multiple uses, go wild 🎀
  • --nosocket=SOCKET — does NOT 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. multiple uses allowed 💖
  • --socket-if=SOCKET:CONDITION — exposes 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 !, like !has-wayland. multiple uses allowed. available since 1.17 ⭐

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

  • --device=DEVICE — exposes 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. multiple uses, bestie 🔥
  • --nodevice=DEVICE — does NOT 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. multiple uses 💅
  • --device-if=DEVICE:CONDITION — exposes 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 !, like !has-input-device. multiple uses allowed. available since 1.17 🌸

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

  • --allow=FEATURE — allows access to a specific feature. this updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth, canbus, per-app-dev-shm. multiple uses allowed 🧚

see flatpak-build-finish(1) for what all these features actually mean.

  • --disallow=FEATURE — disallows access to a specific feature. this updates the [Context] group in the metadata. FEATURE must be one of: devel, multiarch, bluetooth, canbus, per-app-dev-shm. multiple uses allowed 💜
  • --allow-if=FEATURE:CONDITION — allows access to a specific feature conditionally, only when the specified condition is met at runtime. this overrides the Context section from the application metadata. FEATURE must be one of: devel, multiarch, bluetooth. CONDITION must be one of: true, false, has-input-device, has-wayland, has-usb-device, has-usb-portal. conditions can be negated with !, like !has-input-device. multiple uses allowed. available since 1.17 ✨

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

  • --filesystem=FILESYSTEM — lets the application access a subset of the filesystem. this 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 the location is read-only. the optional :create suffix means the location is read-write AND gets created if it doesn't already exist. multiple uses allowed. check the "[Context] filesystems" list in flatpak-metadata(5) for what all these filesystems actually mean 👑
  • --nofilesystem=FILESYSTEM — undoes the effect of a previous --filesystem=FILESYSTEM from the app's manifest or a lower-precedence layer of overrides, and/or removes a previous --filesystem=FILESYSTEM from this layer of overrides. this overrides the Context section of the application metadata. FILESYSTEM takes the same values as for --filesystem, but the :ro and :create suffixes are not used here. multiple uses allowed 💖
lowkey important: this option does NOT block access to a more narrowly-scoped --filesystem. for example, if an application has the equivalent of --filesystem=xdg-config/MyApp in its manifest or as a system-wide override, and you do flatpak override --user --nofilesystem=home as a per-user override, then it gets blocked from most of the home directory, but it's still allowed to access $XDG_CONFIG_HOME/MyApp. sneaky, right? 😭

and as a special case: --nofilesystem=host:reset ignores ALL --filesystem permissions inherited from the app manifest or a lower-precedence layer of overrides, on top of doing the --nofilesystem=host thing. full reset energy 💀

  • --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 🦋
  • --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 just like --env would. this is the move when you want to keep environment variables and their values from being visible to other users. privacy slay 💅

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 🔥

  • --own-name=NAME — lets the application own the well-known name NAME on the session bus. this overrides the Context section from the application metadata. multiple uses allowed 💜
  • --talk-name=NAME — lets the application talk to the well-known name NAME on the session bus. this overrides the Context section from the application metadata. multiple uses allowed 🌸
  • --no-talk-name=NAME — does NOT let the application talk to the well-known name NAME on the session bus. this overrides the Context section from the application metadata. multiple uses allowed 🙈
  • --system-own-name=NAME — lets the application own the well known name NAME on the system bus. if NAME ends with .*, it lets the application own all matching names. this overrides the Context section from the application metadata. multiple uses allowed 👑
  • --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 application talk to all matching names. this overrides the Context section from the application metadata. multiple uses allowed ⭐
  • --system-no-talk-name=NAME — does NOT let the application talk to the well known name NAME on the system bus. if NAME ends with .*, it lets the application talk to all matching names. this overrides the Context section from the application metadata. multiple uses allowed 💀
  • --persist=FILENAME — if the application 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. multiple uses allowed 🍓
  • --reset — removes overrides. if an APP is given, it removes the overrides for that application; otherwise it removes the global overrides. clean slate, iconic 🧚
  • --show — shows overrides. if an APP is given, it shows the overrides for that application; otherwise it shows the global overrides. peek behind the curtain ✨
  • -v, --verbose — prints debug information while the command is processing. the receipts, basically 📝
  • --ostree-verbose — prints OSTree debug information while the command is processing. deeper receipts, for the OSTree girlies 🌈

🎀 EXAMPLES 🎀

okay bestie, real talk — this is the part where it all clicks. three little lines, three big moods 💖

$ flatpak override --nosocket=wayland org.gnome.gedit

this one's like... "bestie, no wayland for you." we're telling org.gnome.gedit it doesn't get the wayland socket, periodt. just blocking that one doorway and moving on with our lives ✨

$ flatpak override --filesystem=home org.mozilla.Firefox

and HERE'S the iconic one — we're handing org.mozilla.Firefox the keys to your entire home directory. that's a lot of trust, ngl. slay for a browser that genuinely needs it, but be a little discerning about who you give this to 👀

$ flatpak override --socket-if=x11:!has-wayland org.example.App

Grant X11 socket access only when not running in a Wayland session.

lowkey the most galaxy-brain of the three 🧠✨ conditional sockets!! we're saying: give org.example.App the x11 socket only if it does not have has-wayland. so on Wayland, no X11 for you; on a plain X11 session, come on in. it's giving "i contain multitudes" 💅

✨ SEE ALSO ✨

go read these next, they're the whole friend group 🫶

  • flatpak(1) — the main character herself, all the general flatpak lore 👑
  • flatpak-run(1) — everything about actually running apps, which is what all your overrides are quietly feeding into 🦋

and that's the page, bestie!! 🌸 this one's from the flatpak crew, section 1 of the manual — FLATPAK OVERRIDE(1), no cap. go forth and override responsibly, mwah 💅💖🌈

📦 where this page comes from