Skip to main content
niri is a Wayland compositor, not a complete desktop environment. To have a fully functional desktop, you’ll need to install and configure additional software components.
Most of this software is essential for normal desktop functionality. Flatpak apps, screen sharing, notifications, and file pickers will not work without the proper components installed.

​
Notification Daemon

Many applications rely on notifications to communicate with users. Without a notification daemon, you won’t see notifications from apps.

mako

A lightweight Wayland notification daemon that works well with niri

​
Setup

Start mako using one of these methods:
Create a systemd user service for mako. See the Example systemd Setup page for details.

​
Portals

Portals provide a cross-desktop API for applications to access system functionality like file pickers, screen sharing, and UI settings. Flatpak apps require working portals.
Portals require running niri as a session (via niri-session script or from a display manager). They will not work if you run niri in windowed mode.

​
Required Portal Packages

1

Install xdg-desktop-portal-gtk

This is the default fallback portal that implements most basic functionality.
# Fedora
sudo dnf install xdg-desktop-portal-gtk

# Ubuntu/Debian
sudo apt install xdg-desktop-portal-gtk

# Arch Linux
sudo pacman -S xdg-desktop-portal-gtk
2

Install xdg-desktop-portal-gnome

Required for screencasting and screen recording support.
# Fedora
sudo dnf install xdg-desktop-portal-gnome

# Ubuntu/Debian
sudo apt install xdg-desktop-portal-gnome

# Arch Linux
sudo pacman -S xdg-desktop-portal-gnome
3

Install gnome-keyring

Implements the Secret portal, required for password management in certain apps.
# Fedora
sudo dnf install gnome-keyring

# Ubuntu/Debian
sudo apt install gnome-keyring

# Arch Linux
sudo pacman -S gnome-keyring

​
Portal Configuration

The niri-portals.conf file configures which portal implementations to use. This file must be installed in the correct location (see Getting Started - Manual Installation).
Starting from xdg-desktop-portal-gnome version 47.0, the portal uses Nautilus as the default file chooser. You must install nautilus for file picker dialogs to work.
If you prefer a different file manager:
1

Edit niri-portals.conf

Open /usr/local/share/xdg-desktop-portal/niri-portals.conf (or the appropriate location for your installation).
2

Change file chooser portal

To use the GTK file chooser instead of Nautilus, set:
org.freedesktop.impl.portal.FileChooser=gtk;

​
Portal Functionality

Once portals are properly configured, systemd will start them on-demand automatically.
Flatpak apps will read GNOME UI settings through the portals. For example, to enable dark mode:
dconf write /org/gnome/desktop/interface/color-scheme '"prefer-dark"'
The GNOME portal provides screen sharing and recording functionality. This is essential for screen sharing in browsers and video conferencing apps.
Do not set the GDK_BACKEND environment variable globally as this will break the screencast portal.

​
Authentication Agent

An authentication agent is required when applications need to request root permissions or elevated privileges.

plasma-polkit-agent

KDE’s polkit authentication agent works well with niri

​
Setup

Start the authentication agent using one of these methods:
Start plasma-polkit-agent with systemd. See the Example systemd Setup page for details.
On Fedora, you need to override the systemd service to add the correct dependency:
systemctl --user edit --full plasma-polkit-agent.service
Then add After=graphical-session.target to the service file.

​
Xwayland

To run X11 applications like Steam, Discord, or older apps that don’t support Wayland natively, you need Xwayland support.

xwayland-satellite

A standalone Xwayland server for Wayland compositors

​
Installation

# Arch Linux
sudo pacman -S xwayland-satellite

# Fedora
sudo dnf copr enable yalter/xwayland-satellite
sudo dnf install xwayland-satellite
For detailed setup instructions and configuration, see the Xwayland documentation.

​
Essential Software Summary

Notifications

mako or similar notification daemonRequired for app notifications

Portals

xdg-desktop-portal-gtkxdg-desktop-portal-gnomegnome-keyringRequired for Flatpak, file pickers, screen sharing

Authentication

plasma-polkit-agent or similarRequired for privilege elevation

File Manager

nautilus or configure GTK portalRequired for file picker dialogs

Xwayland

xwayland-satelliteRequired for X11 apps

Terminal

alacritty (default) or your preferenceRequired for command-line access

App Launcher

fuzzel (default) or rofi/wofiRequired for launching applications

Screen Locker

swaylock or similarRecommended for security
While not strictly required, these tools enhance the desktop experience:
  • Status bar: waybar, yambar, or i3status-rust for system information
  • Screen recorder: wf-recorder or obs-studio for recording sessions
  • Screenshot tool: grim + slurp (included in default niri config)
  • Clipboard manager: cliphist or wl-clipboard for clipboard history
  • Volume control: pavucontrol or similar for audio management
  • Network manager: nm-applet or similar for network configuration

​
Verification

To verify your setup is working correctly:
1

Test notifications

notify-send "Test" "Notification test"
You should see a notification appear on screen.
2

Test portals

Open a Flatpak application and try using a file picker. It should open without errors.
3

Test authentication

Run a command that requires root privileges. You should see an authentication dialog.
For a more integrated desktop experience, consider using a complete desktop shell like DankMaterialShell, which includes many of these components pre-configured.

​
Next Steps

Configuration

Customize niri to match your workflow and preferences

Xwayland Setup

Detailed guide for setting up X11 application support

Build docs developers (and LLMs) love

Get started for freeTalk to us