Niri

Niri
is a scrollable tiling
Wayland
compositor. Unlike
Sway
or
Hyprland
, Niri arranges the windows in an infinite horizontal desktop, where you can scroll to the left or to the right (although more advanced layouts are possible). It is similar to
GNOME
's PaperWM and
KDE
's
Karousel
.
Installation
Niri can be
installed
with the
niri
package. Additionally, to have a better experience, you may want to install:
fuzzel
: default application launcher in Niri
mako
: notifications
waybar
: a Wayland bar
xdg-desktop-portal-gtk
,
xdg-desktop-portal-gnome
: to be able to do screen sharing
alacritty
: default terminal in Niri
swaybg
: background image
swayidle
,
swaylock
: to lock the screen on idle status
xwayland-satellite
: to run X11 apps
udiskie
: to manage and auto-mount USB drives
dms-shell-niri
or
noctalia-shell
AUR
: complete desktop shell
Starting
Niri comes with a
desktop entry
that can be sourced by
display managers
; selecting it will run
niri-session
which handles exporting
environment variables
to
systemd
.
Additionally you can start Niri from a
getty
by executing:
niri-session -l
This can be paired with
auto login
to have a seamless
boot
experience.
Configuration
Niri reads the configuration from
~/.config/niri/config.kdl
. It is a KDL file, divided by sections. The default configuration, created on the first run, documents the default options with comments. However, options introduced with updates will not be documented in the user's configuration; you may check
Niri's official documentation
instead.
Niri automatically applies the configuration when it's saved. The live reload of invalid configuration won't crash Niri; instead, the last working state is preserved, and the user is notified of the configuration error.
niri validate
can be invoked to validate the configuration outside of a Niri session.
Keymap
To configure the keymap, edit the
input/keyboard/xkb
section.
For example, if you want to have a "US Int Alt Gr" layout with
CapsLock
acting as
Ctrl
key:
~/.config/niri/config.kdl
input {
    keyboard {
        xkb {
            layout "us"
            variant "altgr-intl"
            options "ctrl:nocaps"
        }
    }
    ...
}
Outputs
First run
niri msg outputs
to get an overview of the outputs recognized by Niri. Then you can apply configs to each monitor. For example to set the HDMI monitor to 2560x1440 60Hz with a 1.2 scaling, and turning off the laptop monitor, set the following:
~/.config/niri/config.kdl
output "HDMI-A-1" {
    mode "2560x1440@60.000"
    scale 1.2
}

output "eDP-1" {
    off
}
Note
Alternatively, you can use
kanshi
to set up dynamic layouts, for example, if you want to turn off an internal laptop screen when docked to a monitor.
Bindings
The binds section allows to set up the different key combinations that have effect on Niri. Many bindings are already set in the default configuration generated on first launch. These are all remappable.
Please note that Niri does
not
load any default bindings. If a binding is not specified in the configuration, it will not be active. "Defaults" are simply bindings that are present in the automatically generated configuration. Therefore, take care when removing the bindings. It is recommended to instead comment out unused bindings.
Bindings are defined using the modifiers keys appended with a
+
sign and the action between brackets. The special action 'spawn' will launch a program. For example, you will find the following bindings that spawn
alacritty
and
fuzzel
on
Mod+T
and
Mod+D
respectively.
Mod
is usually the
Super
key if running standalone, but it is
Alt
if it is running inside of another compositor.
~/.config/niri/config.kdl
binds {
    ...
    Mod+T { spawn "alacritty"; }
    Mod+D { spawn "fuzzel"; }
    ...
}
Note that all space-separated arguments to processes started by
spawn
must be enclosed in quotes:
~/.config/niri/config.kdl
binds {
    ...
    Mod+Ctrl+semicolon {
        spawn "swaylock" "-c" "121212" "-e" "-f" "-F"
    }
    ...
}
WASD-like navigation
It is possible to configure Niri workspaces and bindings so that jumping through windows follows a navigation similar to WASD as in games.
~/.config/niri/config.kdl
binds {
    ...
    Mod+A { focus-column-left; }
    Mod+S { focus-window-or-workspace-down; }
    Mod+W { focus-window-or-workspace-up; }
    Mod+D { focus-column-right; }
    ...
}
Be aware that this config will probably need other bindings to be remapped as well. Also, some people may prefer to have the WASD navigation on the right-hand side, or have a more Vim-like navigation.
Autostart
Niri allows some programs to be started alongside with Niri. 
For example, some of the programs mentioned beforehand like
mako
,
waybar
and
swayidle
/
swaylock
can be configured:
~/.config/niri/config.kdl
spawn-at-startup "mako"
spawn-at-startup "waybar"
spawn-at-startup "swayidle" "-w" "timeout" "601" "niri msg action power-off-monitors" "timeout" "600" "swaylock -f" "before-sleep" "swaylock -f"
Note that these processes are tied to the Niri session, and they will be killed when Niri exits
or
is suspended. To make a process persist, you may set it to a background task by providing the
"&"
argument.
XWayland
Niri does not provide XWayland support for running X11 applications. Instead, it recommends using an external tool:
xwayland-satellite
is listed in the optional dependencies. After installation, no configuration is required.
Note
Since niri 25.08,
xwayland-satellite
is integrated out of the box. Ensure xwayland-satellite >= 0.7 is installed and available in $PATH. No manual configuration is required.
Multi GPU Configuration
In laptop (or PC) setups with both integrated graphics and a dedicated GPU, Niri may default to using the dedicated GPU for both the compositor and starting other applications, causing unnecessary battery drain.
Note
For NVIDIA cards, see
PRIME
for how to set your GPU to properly enter a low power state, and how to launch applications with that GPU.
To set what GPU Niri should use, first check which render devices are available on your system:
$ ls -l /dev/dri/by-path/*-render
lrwxrwxrwx 1 root root 13 Jan 10 13:02 /dev/dri/by-path/pci-0000:c1:00.0-render -> ../renderD129
lrwxrwxrwx 1 root root 13 Jan 10 13:02 /dev/dri/by-path/pci-0000:c2:00.0-render -> ../renderD128
Then, use the PCI address to identify the correct device you want to use for Niri in
/dev/dri
:
$ lspci -s c1:00.0
c1:00.0 VGA compatible controller: NVIDIA Corporation GB206M [GeForce RTX 5070 Max-Q / Mobile] (rev a1)
If the first PCI address is the wrong card, try the next one.
Finally add to Niri's configuration and specify the correct render device based on the PCI address you identified:
~/.config/niri/config.kdl
debug {
    render-drm-device "/dev/dri/renderD128"
}
Reboot your computer. You can now check if one of the rendering devices is correctly in a low power state using:
$ cat /sys/class/drm/card*/device/power_state
D3cold
D0
See also
Niri's own wiki