portals.conf(5)

📦
version 1.22.1 · 8 versions
, in fedora 44, ubuntu resolute

💖 portals.conf(5) 💖 — File Formats Manual

okay so bestie, this is the man page for portals.conf, and it's literally the vibe-check file that tells xdg-desktop-portal which portal backend is gonna show up to the party. it lives in the File Formats Manual section, and yes, we're gonna read the whole thing together, no skimming. 🫶

✨ Name ✨

portals.conf — XDG desktop portal configuration. that's it, that's the name, she's iconic. 👑

🌈 SYNOPSIS 🌈

so these are all the places this file can live, and honestly, it's giving "found in many homes":

$XDG_CONFIG_HOME/xdg-desktop-portal/{*-}portals.conf

$XDG_CONFIG_DIRS/xdg-desktop-portal/{*-}portals.conf

/etc/xdg/xdg-desktop-portal/{*-}portals.conf

$XDG_DATA_HOME/xdg-desktop-portal/{*-}portals.conf

$XDG_DATA_DIRS/xdg-desktop-portal/{*-}portals.conf

/usr/share/xdg-desktop-portal/{*-}portals.conf

the {*-} is doing a lot of work there, but we'll get into that, don't worry. 💅

🦋 DESCRIPTION 🦋

so like, xdg-desktop-portal reads a config file to figure out which portal backend should be used to provide the implementation for the requested interface. and this whole mechanism is very similar to the freedesktop.org spec for "Association between MIME types and applications" (mime-apps). iykyk.

desktop environments and OS vendors should provide a default configuration for their chosen portal backends in /usr/share/xdg-desktop-portal/DESKTOP-portals.conf, where DESKTOP is the desktop environment name as it would appear in the XDG_CURRENT_DESKTOP environment variable, after case-folding ASCII upper case to lower case. so for example, KDE should provide /usr/share/xdg-desktop-portal/kde-portals.conf. periodt.

users can override those defaults, or provide configuration for an otherwise unsupported desktop environment, by writing a file ~/.config/xdg-desktop-portal/portals.conf. and if you're a multi-desktop girlie, you can use desktop-specific filenames such as kde-portals.conf which will only be used in the appropriate desktop environment. 💅

similarly, system administrators can provide a default configuration for all users in /etc/xdg-desktop-portal/DESKTOP-portals.conf or /etc/xdg/xdg-desktop-portal/portals.conf. wait, no, bestie, let me reread — it's /etc/xdg-desktop-portal/DESKTOP-portals.conf or /etc/xdg-desktop-portal/portals.conf. slay.

the following locations are searched for configuration, highest precedence first:

  • $XDG_CONFIG_HOME, defaulting to ~/.config
  • each directory in $XDG_CONFIG_DIRS, defaulting to /etc/xdg
  • the build-time sysconfdir for xdg-desktop-portal, usually /etc
  • $XDG_DATA_HOME, defaulting to ~/.local/share (searched only for consistency with other specifications, writing configuration here is not recommended)
  • each directory in $XDG_DATA_DIRS, defaulting to /usr/local/share:/usr/share
  • the build-time datadir for xdg-desktop-portal, usually /usr/share

in each of those locations, for each desktop environment name listed in the XDG_CURRENT_DESKTOP environment variable, xdg-desktop-portal checks for xdg-desktop-portal/DESKTOP-portals.conf, where DESKTOP is the desktop environment name in lower-case. if a desktop-environment-specific configuration file is not found, a non-desktop-specific file xdg-desktop-portal/portals.conf will be read. for example, if XDG_CURRENT_DESKTOP is set to Budgie:GNOME, then xdg-desktop-portal will look for xdg-desktop-portal/budgie-portals.conf, xdg-desktop-portal/gnome-portals.conf and xdg-desktop-portal/portals.conf in that order. the way that it just cascades down the list… obsessed. 😭

🎀 FILE FORMAT 🎀

the format of the portals configuration file is the same .ini format used by systemd unit files or application desktop files. we love a format crossover event.

[preferred]

the main configuration group for preferred portals. she's the main character group. 👑

the following keys can be present in the preferred group:

  • default (string) — the default portal backend to use for every interface, unless the interface is listed explicitly.
  • org.freedesktop.impl.portal.* (string) — one of the valid portal interface implementations exposed by xdg-desktop-portal.

each key in the group contains a semi-colon separated list of portal backend implementation, to be searched for an implementation of the requested interface, in the same order as specified in the configuration file. and additionally, the special values none and * can be used:

  • none — do not provide a portal implementation for this interface. 💀
  • * — use the first portal implementation found, in lexicographical order. ✨

🍓 EXAMPLE 🍓

[preferred]
# Use xdg-desktop-portal-gtk for every portal interface...
default=gtk
# ... except for the ScreenCast interface
org.freedesktop.impl.portal.ScreenCast=gnome

not the comments doing the narration for us 😭 it's literally "gtk for everything… except ScreenCast, that's gnome's job". iconic.

🌸 ENVIRONMENT 🌸

  • XDG_CURRENT_DESKTOP — a colon-separated list of desktop environments, most specific first, used to choose a desktop-specific portal configuration. the default is an empty list.
  • XDG_CONFIG_HOME — the per-user portals.conf file is located in this directory. the default is $HOME/.config.
  • XDG_CONFIG_DIRS — a colon-separated list of system configuration directories and secondary per-user configuration directories. the default is /etc/xdg.
  • XDG_DATA_HOME — a per-user data directory, searched for consistency with other specifications. the default is $HOME/.local/share.
  • XDG_DATA_DIRS — a colon-separated list of system data directories and secondary per-user data directories. the default is /usr/local/share:/usr/share.

five env vars, five little queens, each one knowing exactly what she's about. 💜

👑 SEE ALSO 👑

go read those too, bestie, they're the source material. no cap. 📚✨

and that's the whole page, fr fr. this was portals.conf(5) out of the File Formats Manual — that's the page you just read, and that's the section she belongs to. mwah, take care of your portal configs, and remember: highest precedence first, always. 💖🦋🎀

📦 where this page comes from