Integrating niri

This page contains various bits of information helpful for integrating niri in a distribution. First, 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.

This means that you can customize your distribution defaults by creating /etc/niri/config.kdl. When this file 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.

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. 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.

To make a program run at niri startup without editing the niri config, you can either link its .desktop to ~/.config/autostart/, or use a .service file with WantedBy=graphical-session.target. See the example systemd setup page for some 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

You very likely want to run at least a notification daemon, portals, and an authentication agent. This is detailed on the Important Software page.

On top of that, you may want to preconfigure some desktop shell components to make the experience less barebones. Niri's default config spawns Waybar, which is a good starting point, but you may want to consider changing its default configuration to be less of a kitchen sink, and adding the niri/workspaces module. You will probably also want a desktop background tool (swaybg or awww (which used to be swww)), and a nicer screen locker (compared to the default swaylock), like hyprlock.

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 details on setting it up.
• Many XFCE components work on Wayland, including niri. See their wiki for details.
• There are complete desktop shells based on Quickshell that support niri, for example DankMaterialShell and Noctalia.
• You can run a COSMIC session with niri using cosmic-ext-extra-sessions.