PORTALS.CONF(5) File Formats Manual PORTALS.CONF(5)
NAME
portals.conf - XDG desktop portal configuration
SYNOPSIS
$XDG_CONFIG_HOME/xdg-desktop-portal/{*-}portals.conf
$XDG_CONFIG_DIRS/xdg-desktop-portal/{*-}portals.conf
/etc/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
DESCRIPTION
xdg-desktop-portal uses a configuration file to determine which portal
backend should be used to provide the implementation for the requested
interface. This mechanism is very similar to the freedesktop.org speci-
fication for "Association between MIME types and applications"
(mime-apps).
Desktop environments and OS vendors should provide a default configura-
tion for their chosen portal backends in /usr/share/xdg-desktop-por-
tal/DESKTOP-portals.conf, where DESKTOP is the desktop environment name
as it would appear in the XDG_CURRENT_DESKTOP environment variable, af-
ter case-folding ASCII upper case to lower case. For example, KDE
should provide /usr/share/xdg-desktop-portal/kde-portals.conf.
Users can override those defaults, or provide configuration for an oth-
erwise unsupported desktop environment, by writing a file ~/.con-
fig/xdg-desktop-portal/portals.conf. Users of more than one desktop en-
vironment 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-desktop-portal/portals.conf.
The following locations are searched for configuration, highest prece-
dence 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 con-
sistency with other specifications, writing configuration here is not
recommended)
• each directory in $XDG_DATA_DIRS, defaulting to /usr/lo-
cal/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 desk-
top environment name in lower-case. If a desktop-environment-specific
configuration file is not found, a non-desktop-specific file xdg-desk-
top-portal/portals.conf will be read. For example, if XDG_CURRENT_DESK-
TOP is set to Budgie:GNOME, then xdg-desktop-portal will look for
xdg-desktop-portal/budgie-portals.conf, xdg-desktop-portal/gnome-por-
tals.conf and xdg-desktop-portal/portals.conf in that order.
Only the first configuration file found is read, and lower-precedence
configuration files are ignored. All possible configuration files within
one directory are tried before moving on to the next directory, so for
example ~/.config/xdg-desktop-portal/portals.conf is higher-precedence
than /usr/share/xdg-desktop-portal/kde-portals.conf.
FILE FORMAT
The format of the portals configuration file is the same .ini format
used by systemd unit files or application desktop files.
[preferred]
The main configuration group for preferred portals.
The following keys can be present in the preferred group:
default (string)
The default portal backend to use for every interface, unless the in-
terface 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 re-
quested interface, in the same order as specified in the configuration
file. 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
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 de-
fault is $HOME/.config.
XDG_CONFIG_DIRS
A colon-separated list of system configuration directories and sec-
ondary per-user configuration directories. The default is /etc/xdg.
XDG_DATA_HOME
A per-user data directory, searched for consistency with other speci-
fications. 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/lo-
cal/share:/usr/share.
SEE ALSO
• XDG Base Directory Specification <https://specifications.freedesk-
top.org/basedir-spec/basedir-spec-latest.html>
• XDG Desktop Entry specification <https://specifications.freedesk-
top.org/desktop-entry-spec/desktop-entry-spec-latest.html>
• XDG Association between MIME type and applications specification
<https://specifications.freedesktop.org/mime-apps-spec/mime-apps-spec-
latest.html>
PORTALS.CONF(5)
Generated by dwww version 1.16 on Sat Oct 3 11:23:48 CEST 2026.