Jump to content

Niri

From ArchWiki

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:

Starting

The niri package contains a session which should be recognized automatically by modern display managers like GDM and SDDM.

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 user's configuration; you may check Niri's official documentation instead.

Niri automatically applies the configuration when it's saved. 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
}

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

Spawn at startup

Niri allows some programs to be started alongside with Niri. For example, some of 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 suspended. To make a process persist, you may set it to a background task by providing the "&" argument.

See also