XDG Desktop Portal - ArchWiki

Jump to content
From ArchWiki

Related articles

- Flatpak
- PipeWire#WebRTC screen sharing

This article or section is a candidate for moving to xdg-desktop-portal.

Notes: `xdg-desktop-portal` is the official name of the project. (Discuss in Talk:XDG Desktop Portal)

From the Flatpak documentation:

  Portals are the framework for securely accessing resources from outside an application sandbox. They provide a range of common features to applications, including: Determining network status, opening a file with a file chooser, opening URIs, taking screenshots and screencasts [...]

Portals were designed for use with applications sandboxed through Flatpak, but any application can use portals to provide uniform access to features independent of desktops and toolkits. This is commonly used, for example, to allow screen sharing on Wayland via PipeWire, or to use file open and save dialogs on Firefox that use the same toolkit as your current desktop environment.

## Installation

Install xdg-desktop-portal and one or more backends. The package includes a systemd/User service that will be automatically started via D-Bus.

## Backends

When an application makes a request through a portal, it is handled by `xdg-desktop-portal`, which then forwards it to a backend implementation. This allows a clean way to provide suitable user interfaces that fit into different desktop environments, and access environment-specific APIs for requests like showing notifications or recording the screen. Multiple backends can be installed: for example, a Sway user may use xdg-desktop-portal-wlr for screen sharing support and xdg-desktop-portal-gtk as a fallback for all other interfaces that xdg-desktop-portal-wlr does not implement.

Portal backend definitions are located in `/usr/share/xdg-desktop-portal/portals/*.portal`. Each portal backend file contains a list of interfaces that it can handle, and the desktop environments that it can be used in.

### List of backends and interfaces

The following table lists all backends available and their support for certain common interfaces.

Backend | File chooser | Screenshot and screen cast
--- | --- | ---
xdg-desktop-portal-dde | Yes | Yes, on Deepin Desktop Environment
xdg-desktop-portal-gnome | Yes | Yes, on GNOME
xdg-desktop-portal-gtk | Yes | No
xdg-desktop-portal-kde | Yes | Yes, on KDE
xdg-desktop-portal-hyprland1 | No | Yes, on wlroots
xdg-desktop-portal-lxqt | Yes | No
xdg-desktop-portal-wlr | No | Yes, on wlroots
xdg-desktop-portal-xapp | No | Yes, on Cinnamon
xdg-desktop-portal-liri-gitAUR | Yes | Yes, on Liri
xdg-desktop-portal-shanaAUR | Yes2 | No
xdg-desktop-portal-tdAUR | Yes | No
xdg-desktop-portal-termfilechooser-gitAUR | Yes3 | No

1. works with all wlroots-based compositors, but provides extra functionality when used with Hyprland such as sharing individual windows.
2. redirects requests to GNOME/GTK/KDE/LXQt backends
3. allows using a terminal file manager as a file chooser

## Configuration

When a request is made, `xdg-desktop-portal` will use the `/usr/share/xdg-desktop-portal/DE-portals.conf` file, where DE is based on the `XDG_CURRENT_DESKTOP` environment variable. These files are provided by the desktop environments themselves and determine which backends should be used when a specific environment is running.

If users want to override the desktop environment defaults, or their desktop environment does not provide a default configuration, they may create their own portal configuration file at `$XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf` to determine which backends they want to use, either generally or for each individual interface. If you use multiple desktop environments, you may also create multiple `$XDG_CONFIG_HOME/xdg-desktop-portal/DE-portals.conf` files for each environment.

For example, if your desktop environment does not have a portal backend, and you want to use xdg-desktop-portal-gtk as a generic fallback but also use the LXQt file picker through xdg-desktop-portal-lxqt, you can use the following configuration:

    ~/.config/xdg-desktop-portal/portals.conf

    [preferred]
    default=gtk
    org.freedesktop.impl.portal.FileChooser=lxqt

See portals.conf(5) for more information.

Tip: To use the gtk portal as a fallback, it may be necessary to create the configuration file `DE-portals.conf` or `portals.conf`. See this forum discussion.

## Troubleshooting

### xdg-desktop-portal-wlr does not start automatically on sway

For `xdg-desktop-portal-wlr` to work, the `XDG_CURRENT_DESKTOP` and `WAYLAND_DISPLAY` environment variables have to be set in the systemd user session. `XDG_CURRENT_DESKTOP` has to be set to the name of your compositor, e.g. `XDG_CURRENT_DESKTOP=sway`. `WAYLAND_DISPLAY` is set automatically by the compositor.

Check whether these variables are set with `systemctl --user show-environment`. If they are not set, import these environment variables into the systemd user session and dbus by running the following commands after launching the compositor (e.g., include them in the compositor's configuration file).

    $ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
    $ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=compositor_name

Tip: Sway provides a drop-in file which does this automatically, see Sway#Configuration.

See [1] and [2] for more details.

### Using multiple monitors with xdg-desktop-portal-wlr

`xdg-desktop-portal-wlr` requires an external chooser to select the shared monitor. By default, it looks for slurp, wofi and bemenu in this order. When using slurp, after a request for screen sharing you will be presented with a crosshair cursor and you will need to click the screen you want to share. When using wofi or bemenu, you will be presented with a menu of available displays to share. If no choosers are available, `xdg-desktop-portal-wlr` will fallback to the first monitor found. For more information, see xdg-desktop-portal-wlr(5) § SCREENCAST OPTIONS.

## See also

- Portal Documentation: Lists all APIs applications and backends can implement.

Category:

- Freedesktop.org

Hidden category:

- Pages or sections flagged with Template:Move