Linux has several software environments - native based on the Linux SystemD and D-Bus services, third-party FlatPak and Snap.

Probably everyone knows that FlatPak and Snap application distribution systems use a sandbox mechanism, where applications run in a secure environment.

So that programs running inside the sandbox can have access to computer resources, such as the file system, camera, sound server, a “response” component (backend) is used between Snap/Flatpak and the operating system. This component is called "XDG Desktop Portal". From Flatpak documentation:

"Portals are frameworks for securely accessing resources from outside the sandbox. They provide applications with a number of common functions, including: detecting network status, opening a file with a file picker, opening URIs, taking screenshots, and performing screen casts [...]"

Portals were designed for use with applications isolated through Flatpak, but any application can use portals to provide single access to functionality independent of desktops and toolsets. This is commonly used, for example, to allow screen sharing in Wayland via PipeWire, or to use Firefox's file open and save dialogs, which use the same set of tools as your current desktop environment."

When is the xdg-desktop-portal component needed?

• It is needed when using flatpak and snap

How to install xdg-desktop-portal?

sudo apt update
sudo apt install xdg-desktop-portal xdg-desktop-portal-gtk

How to start the xdg-desktop-portal.service service?

This service starts automatically in the user's environment when accessing interfaces that interact with the operating system. If desired, it can be launched manually to check the operation (state, status, errors), but only in the environment of the current user. Team:

systemctl --user start xdg-desktop-portal.service

Checking service status:

systemctl --user status xdg-desktop-portal.service

What is the working principle of xdg-desktop-portal.service?

The component communicates with the system and Flatpak/Snap using the DBus protocol.

How to remove xdg-desktop-portal.service?

If interaction with the OS is from snap packages, flatpak is not required. you can remove the specified packages

sudo apt purge xdg-desktop-portal xdg-desktop-portal-gtk

Where

• xdg-desktop-portal - main package.
• xdg-desktop-portal-gtk - default extension package for most OS-related functions (launching applications, selecting a file, printing, OS settings, gnome-keyring, etc.)

How to ensure xdg-desktop-portal.service works?

xdg-desktop-portal component needs environment variables

• XDG_RUNTIME_DIR
• XDG_CONFIG_HOME
• XDG_DATA_DIRS
• and others, see XDG description.

Check current desktop environment and other XDG variables:

env | grep XDG

The xdg-desktop-portal configuration files are located in the folder /usr/share/xdg-desktop-portal/. They should not be changed.

Also, the component needs the folder names listed in the file:
~/.config/user-dirs.dirs

Example - viewing a list of user folders:

cat ~/.config/user-dirs.dirs

Result:
#This file is written by xdg-user-dirs-update
#If you want to change or add directories, just edit the line you're
#interested in. All local changes will be retained on the next run.
#Format is XDG_xxx_DIR="$HOME/yyy", where yyy is a shell-escaped
#homedir-relative path, or XDG_xxx_DIR="/yyy", where /yyy is an
#absolute path. No other format is supported.
#
XDG_DESKTOP_DIR="$HOME/Desktop"
XDG_DOWNLOAD_DIR="$HOME/Downloads"
XDG_TEMPLATES_DIR="$HOME/Templates"
XDG_PUBLICSHARE_DIR="$HOME/Public"
XDG_DOCUMENTS_DIR="$HOME/Documents"
XDG_MUSIC_DIR="$HOME/Music"
XDG_PICTURES_DIR="$HOME/Pictures"
XDG_VIDEOS_DIR="$HOME/Video"

This file is created when the command is executed

xdg-user-dirs-update

User folders in the OS are named taking into account the current regional language settings in the user profile. Language settings localization also defines environment variables, which can be viewed using the command locale:

locale

To install in Russian:

sudo update-locale LANG=ru_RU.UTF-8

If the Russian language is selected when installing the OS, no configuration is required.

Addition from 2026:
If FlatPak is installed, edit the ~/.bashrc file.
For example, using the nano text editor:

nano ~/.bashrc

At the end of which add the line:
export XDG_DATA_DIRS="/usr/local/share/:/usr/share/:/var/lib/flatpak/exports/share:/home/vladimir/.local/share/flatpak/exports/share"

Save the file and exit nano:
Ctrl+S, Ctrl+X.

How to ensure the xdg-desktop-portal works if it does not start?

By importing a system variable into the user's environment:

On most OSes this is enough:

systemctl --user import-environment XDG_CURRENT_DESKTOP

In Wayland:

systemctl --user import-environment WAYLAND_DISPLAY  XDG_CURRENT_DESKTOP

Restarting and checking that the portal is working:

systemctl --user start xdg-desktop-portal.service
systemctl --user status xdg-desktop-portal.service

How to check the xdg-desktop-portal.service service?

1) You need to install the FlatPak application, install another application in it, for example, the Chromium browser as written in the previous article.

2) First, let's check that the browser is present in the list of installed FlatPak applications.

flatpak list

3) let's launch

flatpak run org.chromium.Chromium

4) Select the item "Open file" - by pressing the keys Ctrl+O. A system dialog should appear, displaying the contents of your home folder. This means the portal is working.

Debugging

dbus-monitor --session

and launch the application in another window

flatpak run org.chromium.Chromium

And pressing Ctrl+O:

In the window dbus-monitor a lot of text will be output:
string "org.freedesktop.impl.portal.Request"
error time=1729069549.930735 sender=:1.49 -> destination=:1.46 error_name=org.freedesktop.DBus.Error.UnknownMethod reply_serial=163
string "The object at the path "/org/freedesktop/portal/desktop/request/1_88/handle_0 " does not exist"
method call time=1729069549.931375 sender=:1.46 -> destination=:1.49 serial=164 path=/org/freedesktop/portal/desktop; interface=org.freedesktop.impl.portal.FileChooser; member=OpenFile
object path "/org/freedesktop/portal/desktop/request/1_88/handle_0"
string "org.chromium.Chromium"
string "x11:0x3a00019"
string "Open file"
array[
dict entry(
string "modal"
variant boolean true
)
dict entry(
string "filters"
variant array [
]
)
]


Start viewing a URL or document using xdg-open

Instead of launching the application and opening a document from it, you can use a simple command xdg-open "filename" or URL.

For example:

xdg-open https://bfm.ru

or

xdg-open 388643rus.pdf

PDF file for testing - "Message from the Director-General of UNESCO*Audrey Azoulayon the occasion of World Radio Day 13 February 2024":388643rus.pdf

• UNESCO - United Nations for education, sciences, and culture.

sudo flatpak install com.github.tchx84.Flatseal
flatpak run com.github.tchx84.Flatseal

FlatSeal allows you to limit application permissions, similar to the Android settings "Applications and notifications" - "Application permissions":

For example, permissions for the Chromium browser from FlatPak:

• Network - Yes
• Interprocess communication - Yes
• X11 window system - Yes.
• PulseAudio sound server - Yes
• Printing system - Yes
• GPU acceleration (device=dri) - default No -> can be changed to Yes
• All devices (webcam) - Yes
• All user files (filesystem=home) - Yes
• Background (can work in the background) - No
• Notifications (can send notifications) - No

Documentation links:

Flatpak Desktop Integration
XDG Desktop Portal
*flatpak-xdg-utils

Related publications

Working with Flatpak or APT through a proxy server

Fixing Linux Mint boot problem with integrated Intel graphics card

Stop and disable TimeShift to save disk space

Troubleshooting L2TP/IPsec connection errors "Could not add IPsec connection" and "no acceptable traffic selectors found"

Hard disk partitioning for installing Linux Mint on an old PC with BIOS in GPT mode