ja:Niri zh-hans: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: complete desktop shell

• niri-settings-git: configuration GUI

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 is saved. The live reload of invalid configuration will not 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:

input {
    keyboard {
        xkb {
            layout "us"
            variant "altgr-intl"
            options "ctrl:nocaps"
        }
    }
    ...
}

~/.config/niri/config.kdl

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:

output "HDMI-A-1" {
    mode "2560x1440@60.000"
    scale 1.2
}

output "eDP-1" {
    off
}

~/.config/niri/config.kdl

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.

binds {
    ...
    Mod+T { spawn "alacritty"; }
    Mod+D { spawn "fuzzel"; }
    ...
}

~/.config/niri/config.kdl

Note that all space-separated arguments to processes started by spawn must be enclosed in quotes:

binds {
    ...
    Mod+Ctrl+semicolon {
        spawn "swaylock" "-c" "121212" "-e" "-f" "-F"
    }
    ...
}

~/.config/niri/config.kdl

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.

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

~/.config/niri/config.kdl

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:

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"

~/.config/niri/config.kdl

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.

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.

To set what GPU Niri should use, first check which render devices are available on your system:

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

$ ls -l /dev/dri/by-path/*-render

Then, use the PCI address to identify the correct device you want to use for Niri in /dev/dri:

c1:00.0 VGA compatible controller: NVIDIA Corporation GB206M [GeForce RTX 5070 Max-Q / Mobile] (rev a1)

$ lspci -s c1:00.0

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:

debug {
    render-drm-device "/dev/dri/renderD128"
}

~/.config/niri/config.kdl

Reboot your computer. You can now check if one of the rendering devices is correctly in a low power state using:

D3cold
D0

$ cat /sys/class/drm/card*/device/power_state

See also

• Niri's own wiki