Linux File Dialog Portal Requirements

March 6, 2026 ยท View on GitHub

This document explains the xdg-desktop-portal requirements for running Ferrite on Linux desktop environments, particularly minimal window managers and Wayland compositors.

Overview

Ferrite uses the rfd crate for native file dialogs. On Linux, rfd uses the xdg-desktop-portal standard via the ashpd backend to provide secure, sandbox-compatible file dialogs.

Some Linux desktop environments (particularly minimal window managers and Wayland compositors) require manual installation of xdg-desktop-portal packages for file dialogs to function.

Affected Desktop Environments

The following Linux desktops typically require manual xdg-desktop-portal installation:

Desktop EnvironmentPortal PackageNotes
Hyprlandxdg-desktop-portal-hyprlandAlso requires xdg-desktop-portal-wlr as fallback
Swayxdg-desktop-portal-wlrwlroots-based portal implementation
i3xdg-desktop-portal-wlrUse with XDG_CURRENT_DESKTOP set
bspwmxdg-desktop-portal-wlrMinimal window manager
dwmxdg-desktop-portal-wlrDynamic window manager
awesomewmxdg-desktop-portal-wlrConfigurable window manager
xmonadxdg-desktop-portal-wlrTiling window manager
qtilexdg-desktop-portal-wlrPython-based window manager
riverxdg-desktop-portal-wlrWayland compositor
nirixdg-desktop-portal-wlrScrollable-tiling Wayland compositor
COSMICxdg-desktop-portal-cosmicSystem76's Rust-based DE
Wayfirexdg-desktop-portal-wlr3D Wayland compositor
LabWCxdg-desktop-portal-wlrOpenbox clone for Wayland

Desktop Environments with Native Support

These desktop environments typically have built-in portal support and don't require manual installation:

Desktop EnvironmentStatus
GNOMEBuilt-in (uses xdg-desktop-portal-gnome)
KDE PlasmaBuilt-in (uses xdg-desktop-portal-kde)
XFCEUsually has portal support
MATEUsually has portal support
CinnamonUsually has portal support
LXDEMay need manual installation
LXQtUsually has portal support
BudgieUsually has portal support

Installation Instructions by Distro

Arch Linux (and derivatives: Manjaro, EndeavourOS, Garuda)

sudo pacman -S xdg-desktop-portal xdg-desktop-portal-wlr

# For Hyprland specifically, also install:
sudo pacman -S xdg-desktop-portal-hyprland

Debian / Ubuntu / Pop!_OS / Linux Mint

sudo apt install xdg-desktop-portal xdg-desktop-portal-wlr

Fedora / Nobara

sudo dnf install xdg-desktop-portal xdg-desktop-portal-wlr

openSUSE

sudo zypper install xdg-desktop-portal xdg-desktop-portal-wlr

Configuration

Hyprland Configuration

Add to your ~/.config/hypr/hyprland.conf:

exec-once = /usr/lib/xdg-desktop-portal-hyprland
exec-once = /usr/lib/xdg-desktop-portal

Or if using systemd:

exec-once = systemctl --user import-environment PATH
exec-once = systemctl --user start xdg-desktop-portal-hyprland
exec-once = systemctl --user start xdg-desktop-portal

Sway Configuration

Add to your Sway config:

exec dbus-update-activation-environment --systemd DISPLAY WAYLAND_DISPLAY SWAYSOCK XDG_CURRENT_DESKTOP
exec systemctl --user start xdg-desktop-portal-wlr
exec systemctl --user start xdg-desktop-portal

Setting XDG_CURRENT_DESKTOP

For minimal window managers, ensure XDG_CURRENT_DESKTOP is set correctly:

# Add to ~/.profile or ~/.bashrc
export XDG_CURRENT_DESKTOP=sway  # or hyprland, i3, etc.

How Ferrite Handles Portal Failures

Detection

Ferrite detects the Linux desktop environment by checking the following environment variables:

  1. XDG_CURRENT_DESKTOP - Primary detection method
  2. DESKTOP_SESSION - Fallback detection

Error Handling

When a file dialog fails on a Linux desktop that requires portals:

  1. Logging: A warning is logged:

    File dialog failed on Hyprland. This may indicate missing xdg-desktop-portal.

  2. Error Dialog: An error modal is displayed with:

    • The detected desktop environment name
    • Installation instructions specific to the detected distro
    • A "Copy Install Command" button to copy the command to clipboard

  3. Distro-Specific Instructions: The dialog shows the appropriate package manager command:

    • Arch: pacman -S xdg-desktop-portal xdg-desktop-portal-hyprland
    • Ubuntu: apt install xdg-desktop-portal xdg-desktop-portal-wlr
    • Fedora: dnf install xdg-desktop-portal xdg-desktop-portal-wlr

Code Implementation

The portal error handling is implemented in:

  • src/files/dialogs.rs - Detection functions and DialogResult<T> type
  • src/app/file_ops.rs - Error handling in file operations
  • src/app/dialogs.rs - Portal error dialog UI rendering

Troubleshooting

Dialog Still Fails After Installation

  1. Check portal service is running:

    systemctl --user status xdg-desktop-portal
systemctl --user status xdg-desktop-portal-wlr  # or -hyprland

  2. Restart portal services:

    systemctl --user restart xdg-desktop-portal
systemctl --user restart xdg-desktop-portal-wlr

  3. Verify environment variables:

    echo $XDG_CURRENT_DESKTOP
echo $WAYLAND_DISPLAY

Flatpak-Specific Issues

If running Ferrite as a Flatpak:

  1. Ensure the portal service is running on the host system
  2. The portal dialog may need a navigable starting directory (Ferrite falls back to $HOME)
  3. Check Flatpak permissions with: flatpak info --show-permissions dev.ferrite.Ferrite

rfd Zenity Fallback

As of rfd 0.14+, the library does not automatically fall back to Zenity or KDialog when portals are unavailable. The implementation relies on the xdg-desktop-portal standard.

If you need an alternative file dialog without portals, consider:

  1. Installing the required portal packages (recommended)
  2. Using a desktop environment with native portal support

Environment Variables Reference

VariablePurposeExample Values
XDG_CURRENT_DESKTOPIdentifies the desktop environmenthyprland, sway, gnome, kde
DESKTOP_SESSIONFallback desktop identificationhyprland, sway, gnome
FLATPAK_IDIndicates Flatpak sandboxdev.ferrite.Ferrite
WAYLAND_DISPLAYIndicates Wayland sessionwayland-1
DISPLAYIndicates X11 session:0