Niri - ArchWiki

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
- udiskie: to manage and auto-mount USB drives
- dms-shell-niri or noctalia: complete desktop shell
- niri-settings-gitAUR: 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.

Note When using LXQt, the configuration is located in a different place and will be created at first start; see LXQt#Wayland Session.

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:

    ~/.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, a re-login may be required for it being available in the PATH variable.

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

## Troubleshooting

### Java applications

Some Java-based applications will display a blank window when opened under xwayland-satellite. The official Niri documentation recommends to start the affected applications with the `_JAVA_AWT_WM_NONREPARENTING=1` environment variable. For more details, see Sway#Java applications.

## See also

- Niri's own wiki

Category:

- Wayland compositors

Niri
Add topic