Skip to main content
This page contains various bits of information helpful for integrating niri in a distribution.
For creating a niri package, see the Packaging page.

​
Configuration

Niri will load configuration from $XDG_CONFIG_HOME/niri/config.kdl or ~/.config/niri/config.kdl, falling back to /etc/niri/config.kdl. If both of these files are missing, niri will create $XDG_CONFIG_HOME/niri/config.kdl with the contents of the default configuration file, which are embedded into the niri binary at build time.

​
Distribution Defaults

You can customize your distribution defaults by creating /etc/niri/config.kdl.
When /etc/niri/config.kdl is present, niri will not automatically create a config at ~/.config/niri/, so you’ll need to direct your users how to do it themselves.
Keep in mind that we update the default config in new releases, so if you have a custom /etc/niri/config.kdl, you likely want to inspect and apply the relevant changes too.

​
Configuration Overrides

The default configuration locations can be overridden with the NIRI_CONFIG environment variable.
Since: next release - You can also change the configuration path at runtime via the niri IPC or using the command:
niri msg action load-config-file --path <path-to-config.kdl>
Since: 25.11 - You can split the niri config file into multiple files using include.

​
Xwayland

Xwayland is required for running X11 apps and games, and also the Orca screen reader.
Since: 25.08 - Niri integrates with xwayland-satellite out of the box.

​
xwayland-satellite Integration

The integration requires xwayland-satellite >= 0.7 available in $PATH.
Please consider making niri depend on (or at least recommend) the xwayland-satellite package.
If you had a custom config which manually started xwayland-satellite and set $DISPLAY, you should remove those customizations for the automatic integration to work.
You can change the path where niri looks for xwayland-satellite using the xwayland-satellite top-level option.

​
Keyboard Layout

Since: 25.08 - By default (unless manually configured otherwise), niri reads keyboard layout settings from systemd-localed at org.freedesktop.locale1 over D-Bus.
Make sure your system installer sets the keyboard layout via systemd-localed, and niri should pick it up.

​
Autostart

Niri works with the normal systemd autostart. The default niri.service brings up graphical-session.target as well as xdg-desktop-autostart.target.

​
Autostart Methods

To make a program run at niri startup without editing the niri config, you can use one of these methods:

Desktop Files

Link its .desktop file to ~/.config/autostart/

systemd Services

Use a .service file with WantedBy=graphical-session.target
See the example systemd setup page for detailed examples.
If this is inconvenient, you can also add spawn-at-startup lines in the niri config.

​
Screen Readers

Since: 25.08 - Niri works with the Orca screen reader.
Please see the Accessibility page for details and advice for accessibility-focused distributions.

​
Desktop Components

​
Essential Components

You very likely want to run at least:
  • Notification daemon
  • Portals
  • Authentication agent
This is detailed on the Important Software page.

​
Shell Components

On top of that, you may want to preconfigure some desktop shell components to make the experience less barebones.

​
Waybar

Niri’s default config spawns Waybar, which is a good starting point.
You may want to consider changing its default configuration to be less of a kitchen sink, and adding the niri/workspaces module.

​
Background and Screen Locker

You will probably also want:

​
Complete Desktop Environments

Alternatively, some desktop environments and shells work with niri, and can give a more cohesive experience in one package:

LXQt

Officially supports niri. See their wiki for setup details.

XFCE

Many components work on Wayland, including niri.

Quickshell Desktops

Complete shells like DankMaterialShell and Noctalia

COSMIC

Run a COSMIC session with niri using cosmic-ext-extra-sessions

Build docs developers (and LLMs) love

Get started for freeTalk to us