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:

- 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

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

### Autostart

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.

### XWayland

Niri does not try to implement anything regarding XWayland, required to run apps that use X11. Instead, it recommends using an external tool: xwayland-satellite is listed in the optional dependencies. After installation, you should configure a `DISPLAY` environment variable:

    ~/.config/niri/config.kdl

    environment {
        DISPLAY ":0"
    }

and launch xwayland-satellite at startup. You can do that with the spawn-at-startup command or with a systemd service.

    ~/.config/niri/config.kdl

    spawn-at-startup "xwayland-satellite"

## See also

- Niri's own wiki

Category:

- Wayland compositors