Try niri, the Scrollable-Tiling Wayland Compositor

niri is a Wayland compositor built around a fundamentally different tiling model: instead of splitting a monitor into a grid, windows are arranged in an infinite horizontal scrolling strip per workspace. New windows appear to the right; you scroll left and right through them. If you find traditional tiling layouts mentally taxing to manage, or you want something between a floating desktop and a strict grid tiler, niri is worth a serious look.

Why niri Instead of sway or Hyprland?

sway is a near-faithful Wayland port of i3 — stable, scriptable, widely documented. Hyprland gives you dynamic tiling with heavy animation support and a huge plugin ecosystem. niri's pitch is narrower and more opinionated:

• Scrollable columns, not splits. Every window is a column. You never have to think about splitting directions or layout algorithms.
• Predictable window positions. Opening a terminal always puts it to the right of what you were looking at. Nothing rearranges behind your back.
• Written in Rust. The codebase is small, safe, and compiles fast. Crashes are rare in practice.
• No display-server root access. niri does not run as root and does not require a setuid binary.
• Trade-offs to know: no vertical tiling, no built-in bar (use waybar or ironbar), smaller ecosystem than Hyprland, and some niche Wayland protocols are still being added.

Install niri

Debian / Ubuntu (24.04+)

niri is not yet in the main Debian or Ubuntu repositories as of mid-2025. Install from the official binary releases or build from source. The upstream releases page ships a statically-linked binary tarball.

sudo apt install -y libwayland-client0 libxkbcommon0 libinput10 pipewire
wget https://github.com/YaLTeR/niri/releases/latest/download/niri-x86_64-unknown-linux-gnu.tar.gz
tar xf niri-x86_64-unknown-linux-gnu.tar.gz
sudo install -Dm755 niri /usr/local/bin/niri

Also install the session file so display managers can see it:

sudo install -Dm644 niri.desktop /usr/share/wayland-sessions/niri.desktop

Fedora 40+

niri is packaged in the official Fedora repos from F40 onward.

sudo dnf install -y niri

Arch Linux

niri lives in the extra repository.

sudo pacman -S niri

For the absolute latest git build, the AUR has niri-git:

paru -S niri-git

First Launch

Log out and select niri from your display manager's session menu, or start it directly from a TTY:

niri-session

On first launch with no config file, niri applies built-in defaults. You will see a blank desktop. Press Super+T (if you have configured a terminal) or open a VT to verify it is running:

echo $WAYLAND_DISPLAY
# Output: wayland-1  (or similar)

Configuration Basics

niri uses a single KDL-format config file. Create it at the standard path:

mkdir -p ~/.config/niri
niri --generate-config > ~/.config/niri/config.kdl

The generated file is heavily commented — read it. Key sections to touch immediately:

Spawn your terminal

# Inside config.kdl
binds {
    Mod+T { spawn "foot"; }
    Mod+Return { spawn "foot"; }
    Mod+D { spawn "fuzzel"; }   // app launcher
    Mod+Shift+Q { close-window; }
}

Replace foot with alacritty, kitty, or whatever terminal you use. fuzzel and rofi --wayland both work as launchers.

Set your monitor output

output "DP-1" {
    mode "[email protected]"
    scale 1.0
    transform "normal"
}

Find your output name with:

niri msg outputs

The Scrollable-Tiling Model

Understanding this model removes most of the initial confusion:

• Each workspace is an independent horizontal strip. Think of it as a long roll of paper.
• Each window occupies one column. Columns can hold multiple windows stacked vertically if you explicitly stack them (Mod+Comma / Mod+Period to add/remove from a column).
• The visible area is a viewport scrolling over that strip. You never see the whole workspace at once unless all windows fit.
• Windows to the left of the viewport are not hidden — they are just off-screen, reachable instantly.

Controlling column width

Windows have a proportional width. Cycle through preset widths with:

Mod+R        # cycle width presets (1/3, 1/2, 2/3, full)
Mod+F        # toggle fullscreen
Mod+Shift+F  # toggle fullscreen across all outputs

Set custom proportions per-window-rule in config.kdl:

window-rule {
    match app-id="firefox"
    default-column-width { proportion 0.6; }
}

Essential Keybinds

Action	Default bind
Focus left / right	Mod+H / Mod+L or Mod+Left / Mod+Right
Move window left / right	Mod+Shift+H / Mod+Shift+L
Switch workspace	Mod+1 … Mod+9
Move window to workspace	Mod+Shift+1 … Mod+Shift+9
Stack window into column	Mod+Comma / Mod+Period
Focus window in stack	Mod+K / Mod+J
Move window to next output	Mod+Shift+Arrow
Scroll viewport	Mod+WheelScrollRight / Left
Open overview	Mod+O
Quit niri	Mod+Shift+E

All binds are fully rebindable in the binds { } block. The defaults use Mod (Super/Windows key) but you can swap it to Alt by changing the mod-key setting.

Setting Up a Status Bar

niri has no built-in bar. waybar is the most common choice and has native niri support from waybar 0.10+.

# Arch
sudo pacman -S waybar

# Fedora
sudo dnf install waybar

# Debian/Ubuntu
sudo apt install waybar

Auto-start it from config.kdl:

spawn-at-startup "waybar"

Waybar's niri module surfaces the current workspace index and window title. Use "niri/workspaces" and "niri/window" modules in your waybar config.

Verify Everything Works

After a full logout and login into niri:

# Check niri version
niri --version

# List running windows known to niri
niri msg windows

# Check Wayland and XWayland
echo $WAYLAND_DISPLAY        # should be wayland-1 or similar
echo $DISPLAY                # should be :0 if XWayland is active

To enable XWayland (needed for many legacy apps), add to config.kdl:

xwayland {
    enable true
}

Troubleshooting

Black screen after login

niri started but your terminal bind or spawn-at-startup is wrong. Switch to a TTY (Ctrl+Alt+F2), check journalctl --user -u niri or $XDG_RUNTIME_DIR/niri/stderr.log for errors, fix your config, and restart the session.

Config parse errors

niri validates config on startup and prints exact line numbers. Run validation manually without restarting:

niri validate --config ~/.config/niri/config.kdl

Screen sharing / PipeWire capture not working

Ensure xdg-desktop-portal-gnome or xdg-desktop-portal-gtk is running alongside xdg-desktop-portal. niri supports the PipeWire screencast portal. Add to spawn-at-startup if your session does not launch it automatically:

spawn-at-startup "/usr/libexec/xdg-desktop-portal"
spawn-at-startup "/usr/libexec/xdg-desktop-portal-gtk"

High CPU from animations

niri animates scrolling and window open/close. On low-power hardware, reduce or disable animations in config.kdl:

animations {
    slowdown 0.3    // 1.0 = default speed; lower is faster
}