1PORTALS.CONF(5) File Formats Manual PORTALS.CONF(5)
2
6 portals.conf - XDG desktop portal configuration
7
9 $XDG_CONFIG_HOME/xdg-desktop-portal/{*-}portals.conf
10 $XDG_CONFIG_DIRS/xdg-desktop-portal/{*-}portals.conf
12 /etc/xdg-desktop-portal/{*-}portals.conf
14 $XDG_DATA_HOME/xdg-desktop-portal/{*-}portals.conf
16 $XDG_DATA_DIRS/xdg-desktop-portal/{*-}portals.conf
18 /usr/share/xdg-desktop-portal/{*-}portals.conf
20
22 xdg-desktop-portal uses a configuration file to determine which portal
23 backend should be used to provide the implementation for the requested
24 interface. This mechanism is very similar to the freedesktop.org spec‐
25 ification for "Association between MIME types and applications"
26 (mime-apps).
27 Desktop environments and OS vendors should provide a default configura‐
29 tion for their chosen portal backends in /usr/share/xdg-desktop-por‐
30 tal/DESKTOP-portals.conf, where DESKTOP is the desktop environment name
31 as it would appear in the XDG_CURRENT_DESKTOP environment variable, af‐
32 ter case-folding ASCII upper case to lower case. For example, KDE
33 should provide /usr/share/xdg-desktop-portal/kde-portals.conf.
34 Users can override those defaults, or provide configuration for an oth‐
36 erwise unsupported desktop environment, by writing a file ~/.con‐
37 fig/xdg-desktop-portal/portals.conf. Users of more than one desktop en‐
38 vironment can use desktop-specific filenames such as kde-portals.conf
39 which will only be used in the appropriate desktop environment.
40 Similarly, system administrators can provide a default configuration
42 for all users in /etc/xdg-desktop-portal/DESKTOP-portals.conf or
43 /etc/xdg-desktop-portal/portals.conf.
44 The following locations are searched for configuration, highest prece‐
46 dence first:
47 • $XDG_CONFIG_HOME, defaulting to ~/.config
49 • each directory in $XDG_CONFIG_DIRS, defaulting to /etc/xdg
51 • the build-time sysconfdir for xdg-desktop-portal, usually /etc
53 • $XDG_DATA_HOME, defaulting to ~/.local/share (searched only for con‐
55 sistency with other specifications, writing configuration here is not
56 recommended)
57 • each directory in $XDG_DATA_DIRS, defaulting to /usr/lo‐
59 cal/share:/usr/share
60 • the build-time datadir for xdg-desktop-portal, usually /usr/share
62 In each of those locations, for each desktop environment name listed in
64 the XDG_CURRENT_DESKTOP environment variable, xdg-desktop-portal checks
65 for xdg-desktop-portal/DESKTOP-portals.conf, where DESKTOP is the desk‐
66 top environment name in lower-case. If a desktop-environment-specific
67 configuration file is not found, a non-desktop-specific file xdg-desk‐
68 top-portal/portals.conf will be read. For example, if XDG_CUR‐
69 RENT_DESKTOP is set to Budgie:GNOME, then xdg-desktop-portal will look
70 for xdg-desktop-portal/budgie-portals.conf, xdg-desktop-por‐
71 tal/gnome-portals.conf and xdg-desktop-portal/portals.conf in that or‐
72 der.
73 Only the first configuration file found is read, and lower-precedence
75 configuration files are ignored. All possible configuration files
76 within one directory are tried before moving on to the next directory,
77 so for example ~/.config/xdg-desktop-portal/portals.conf is
78 higher-precedence than /usr/share/xdg-desktop-portal/kde-portals.conf.
79 FILE FORMAT
81 The format of the portals configuration file is the same .ini format
82 used by systemd unit files or application desktop files.
83 [preferred]
85 The main configuration group for preferred portals.
86 The following keys can be present in the preferred group:
88 default (string)
90 The default portal backend to use for every interface, unless the
91 interface is listed explicitly.
92 org.freedesktop.impl.portal.* (string)
94 One of the valid portal interface implementations exposed by
95 xdg-desktop-portal.
96 Each key in the group contains a semi-colon separated list of portal
98 backend implementation, to be searched for an implementation of the re‐
99 quested interface, in the same order as specified in the configuration
100 file. Additionally, the special values none and * can be used:
101 none
103 Do not provide a portal implementation for this interface.
104 *
106 Use the first portal implementation found, in lexicographical order.
107 EXAMPLE
109 [preferred]
110 # Use xdg-desktop-portal-gtk for every portal interface...
111 default=gtk
112 # ... except for the Screencast interface
113 org.freedesktop.impl.portal.Screencast=gnome
114 ENVIRONMENT
116 XDG_CURRENT_DESKTOP
117 A colon-separated list of desktop environments, most specific first,
118 used to choose a desktop-specific portal configuration. The default
119 is an empty list.
120 XDG_CONFIG_HOME
122 The per-user portals.conf file is located in this directory. The de‐
123 fault is $HOME/.config.
124 XDG_CONFIG_DIRS
126 A colon-separated list of system configuration directories and sec‐
127 ondary per-user configuration directories. The default is /etc/xdg.
128 XDG_DATA_HOME
130 A per-user data directory, searched for consistency with other spec‐
131 ifications. The default is $HOME/.local/share.
132 XDG_DATA_DIRS
134 A colon-separated list of system data directories and secondary
135 per-user data directories. The default is /usr/lo‐
136 cal/share:/usr/share.
137 SEE ALSO
139 • XDG Base Directory Specification
140 • XDG Desktop Entry specification
142 • XDG Association between MIME type and applications specification
144 PORTALS.CONF(5)