Niri: Scrollable Tiling Wayland Compositor Guide (2026)

Posted: April 13, 2026 to Technology.

Niri is a scrollable tiling Wayland compositor written in Rust that introduces a fundamentally different approach to window management. Instead of dividing your screen into a static grid of tiles, Niri arranges windows in an infinite horizontal strip that you scroll through, one column at a time. If you have ever felt constrained by the fixed-grid model of i3, Sway, or Hyprland, Niri removes that constraint entirely. This guide covers installation, configuration, and real-world workflow patterns based on our team’s daily experience running Niri on NixOS workstations.

At Petronella Technology Group, we run Linux on every engineering workstation. Our team switched to Niri for security research, AI development, and infrastructure management after evaluating every major Wayland compositor. We wrote this guide because the scrollable paradigm requires a different mental model than traditional tiling, and most existing documentation does not explain the practical workflow implications.

What Is Niri and How Scrollable Tiling Works

Traditional tiling window managers divide your monitor into regions. Open four windows on a workspace and each gets roughly a quarter of the screen. The more windows you open, the smaller each one becomes. This works well when you have two or three windows, but it breaks down when you need six or eight applications visible across a workflow. You either stack windows in tabs (losing the visual benefit of tiling) or spread them across multiple workspaces (losing spatial context).

Niri solves this with a scrollable layout. Every workspace is an infinite horizontal strip. Windows occupy columns within that strip, and each column takes a configurable proportion of the screen width. You scroll left and right to bring different windows into view, similar to how you scroll a document. The key insight is that your monitor becomes a viewport into a wider workspace rather than a container that must fit everything at once.

Think of it like a horizontal timeline of windows. Your terminal might be to the left, your browser in the center, and your monitoring dashboards to the right. You focus on one or two columns at a time and scroll to reach others. There is no juggling of workspace numbers or memorizing which workspace holds which application. Everything lives on one continuous strip, arranged in the order you opened it or manually repositioned it.

Niri is written in Rust and built on Smithay, a Wayland compositor library. Rust’s memory safety guarantees mean entire classes of bugs (use-after-free, buffer overflows, data races) are eliminated at compile time. For a compositor that sits between your GPU and every application on your system, this is not an academic concern. Display servers are high-privilege software, and memory safety reduces the attack surface meaningfully.

The project was created by YaLTeR and has been under active development since 2023. It reached a stable, daily-drivable state in 2024, and the 0.1.x releases through 2025-2026 have added features like window rules, animations, screen capture portals, and NVIDIA support. It is not yet at 1.0, but the pace of development and the stability of current releases make it suitable for production workstations.

Why Niri Over Hyprland, Sway, or i3

Every compositor serves a different philosophy. Niri is not universally better than the alternatives. It excels in specific workflows and falls short in others. Here is an honest comparison.

Niri vs Sway

Sway is the mature, battle-tested Wayland compositor that aims for i3 compatibility. It tiles windows into fixed grids, supports tabbed and stacked layouts, and has been stable for years. If you want a compositor that works like i3 but on Wayland, Sway is the safe choice. Niri is different in kind, not degree. The scrollable model means you never resize windows to fit more on screen. Instead, you scroll. If your workflow involves many windows that you access sequentially (editing code, checking documentation, reviewing logs, monitoring dashboards), Niri’s model reduces the cognitive overhead of managing where everything is. If you frequently need to see four or more windows simultaneously in a fixed arrangement, Sway’s grid model handles that better.

Niri vs Hyprland

Hyprland is the eye-candy champion: animations, blur, rounded corners, gradients, and a plugin ecosystem. It is written in C++ and focuses on visual polish alongside tiling. We have a complete Hyprland setup guide on our blog that covers its strengths. Niri takes the opposite approach. It is visually clean but not flashy. It does include configurable animations (window open/close, workspace switch), but the focus is on the scrollable workflow paradigm rather than visual effects. Niri is also written in Rust rather than C++, which provides stronger memory safety guarantees. If you want a compositor that makes your desktop look impressive in screenshots, Hyprland wins. If you want a compositor that disappears into the background while you work, Niri is the better fit.

Niri vs i3

i3 is X11-only. In 2026, starting a new Linux desktop setup on X11 means accepting a protocol that permits any application to keylog any other application. There is no path from i3 to Wayland; you must switch compositors entirely. If you are coming from i3 and value keyboard-driven workflow, Niri preserves that experience while adding the security isolation of Wayland and the spatial benefits of scrollable tiling.

Niri vs GNOME

GNOME provides a complete desktop environment with accessibility features, a settings GUI, integrated search, and broad hardware support. It is the right choice for users who want a desktop that works out of the box. Niri is for users who want to assemble their own desktop from individual components and are comfortable editing configuration files. GNOME uses approximately 800 MB of RAM at idle; a Niri session with Waybar and supporting tools uses around 120-180 MB.

Installation: NixOS, Arch, and Fedora

NixOS (Declarative Configuration)

NixOS is our team’s primary platform, and Niri integrates cleanly through the niri-flake or the nixpkgs module. The declarative approach means your compositor configuration is version-controlled alongside your entire system configuration. For more on how we use NixOS, see our NixOS AI infrastructure overview.

# configuration.nix
programs.niri.enable = true;

# Enable XWayland for legacy X11 apps
programs.xwayland.enable = true;

# Recommended: enable the portal for screen sharing
xdg.portal = {
  enable = true;
  extraPortals = [ pkgs.xdg-desktop-portal-gnome ];
};

# For NVIDIA GPUs (see NVIDIA section)
hardware.nvidia = {
  modesetting.enable = true;
  open = true;
};
hardware.graphics.enable = true;

For Home Manager users, niri-flake provides a programs.niri module that generates config.kdl from Nix expressions. This is the approach our team uses because it keeps all configuration in a single flake, making workstation rebuilds fully reproducible across machines.

# home.nix (with niri-flake)
programs.niri = {
  settings = {
    input.keyboard.xkb.layout = "us";
    outputs."DP-1".scale = 1.0;
    binds = {
      "Mod+Return".action.spawn = [ "kitty" ];
      "Mod+D".action.spawn = [ "fuzzel" ];
      "Mod+Q".action = "close-window";
    };
  };
};

Arch Linux

Niri is available in the official Arch repositories:

sudo pacman -S niri

For the latest development version, the AUR provides niri-git. Install companion tools immediately:

sudo pacman -S waybar fuzzel swaylock mako wl-clipboard kitty

Start Niri from a TTY by running niri-session, which launches Niri along with any configured autostart programs and the D-Bus session.

Fedora

Fedora ships Niri in the official repositories starting with Fedora 40. Install with:

sudo dnf install niri

Fedora’s SELinux may block IPC socket access if you use custom scripts that communicate with Niri via niri msg. Check ausearch -m avc for denials and create a local policy if needed. The COPR repository yalter/niri provides builds that track upstream more closely if the Fedora-packaged version lags behind.

Configuration with config.kdl

Niri uses KDL (KDocument Language) for its configuration file, located at ~/.config/niri/config.kdl. KDL is a structured document language that is cleaner than TOML for nested configurations and more readable than JSON. The configuration is hot-reloaded: save the file and changes apply immediately without restarting the compositor.

Input Settings

input {
    keyboard {
        xkb {
            layout "us"
        }
        repeat-delay 300
        repeat-rate 50
    }

    touchpad {
        tap
        natural-scroll
        accel-speed 0.3
    }

    mouse {
        accel-speed 0.0
    }
}

Layout and Column Behavior

This is where Niri differs fundamentally from other compositors. Instead of configuring tile ratios, you configure column widths and gaps:

layout {
    gaps 8
    center-focused-column "never"

    preset-column-widths {
        proportion 0.33333
        proportion 0.5
        proportion 0.66667
    }

    default-column-width {
        proportion 0.5
    }

    focus-ring {
        width 2
        active-color "#7fc8ff"
        inactive-color "#505050"
    }

    border {
        off
    }

    struts {
        left 0
        right 0
        top 0
        bottom 0
    }
}

The preset-column-widths block defines widths you can cycle through with a keybinding. A window starts at default-column-width (here, 50% of the screen), and you press a key to cycle it to one-third, half, or two-thirds width. The center-focused-column option controls whether the currently focused column is centered on screen when you scroll to it. Setting it to "always" creates a centered reading experience; "never" keeps the scroll position more predictable.

Animations

animations {
    workspace-switch {
        spring damping-ratio=1.0 stiffness=1000 epsilon=0.0001
    }

    window-open {
        duration-ms 200
        curve "ease-out-expo"
    }

    window-close {
        duration-ms 150
        curve "ease-out-quad"
    }

    horizontal-view-movement {
        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
    }

    window-movement {
        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
    }

    window-resize {
        spring damping-ratio=1.0 stiffness=800 epsilon=0.0001
    }
}

Niri uses spring physics for most animations, which produces natural-feeling motion. The damping-ratio controls overshoot (1.0 is critically damped with no bounce), stiffness controls speed, and epsilon determines when the animation is considered complete.

Keybindings and Navigation

Navigation in Niri is built around the scrollable column model. You move focus left/right between columns and up/down between windows within a column. Here is a practical keybinding configuration:

binds {
    // Launch applications
    Mod+Return { spawn "kitty"; }
    Mod+D { spawn "fuzzel"; }
    Mod+Q { close-window; }
    Mod+Shift+E { quit; }

    // Focus movement
    Mod+H { focus-column-left; }
    Mod+L { focus-column-right; }
    Mod+K { focus-window-up; }
    Mod+J { focus-window-down; }

    // Move columns
    Mod+Shift+H { move-column-left; }
    Mod+Shift+L { move-column-right; }
    Mod+Shift+K { move-window-up; }
    Mod+Shift+J { move-window-down; }

    // Column width
    Mod+R { switch-preset-column-width; }
    Mod+F { maximize-column; }
    Mod+Shift+F { fullscreen-window; }
    Mod+Minus { set-column-width "-10%"; }
    Mod+Equal { set-column-width "+10%"; }

    // Consume/expel windows into/from columns
    Mod+BracketLeft { consume-window-into-column; }
    Mod+BracketRight { expel-window-from-column; }

    // Workspaces
    Mod+1 { focus-workspace 1; }
    Mod+2 { focus-workspace 2; }
    Mod+3 { focus-workspace 3; }
    Mod+4 { focus-workspace 4; }
    Mod+5 { focus-workspace 5; }
    Mod+Shift+1 { move-column-to-workspace 1; }
    Mod+Shift+2 { move-column-to-workspace 2; }
    Mod+Shift+3 { move-column-to-workspace 3; }
    Mod+Shift+4 { move-column-to-workspace 4; }
    Mod+Shift+5 { move-column-to-workspace 5; }

    // Monitor focus
    Mod+Shift+Left { move-column-to-monitor-left; }
    Mod+Shift+Right { move-column-to-monitor-right; }

    // Screenshot (requires grim + slurp)
    Print { screenshot; }
    Ctrl+Print { screenshot-screen; }
    Alt+Print { screenshot-window; }

    // Lock screen
    Mod+Escape { spawn "swaylock"; }
}

The consume-window-into-column and expel-window-from-column bindings are unique to Niri. They let you stack multiple windows vertically within a single column (similar to tabs in i3) and then break them apart again. This gives you the flexibility to group related windows without creating a permanent split.

Window Rules and Layout Control

Window rules let you override default behavior for specific applications:

window-rule {
    match app-id=r#"^org\.keepassxc\.KeePassXC$"#
    open-floating true
}

window-rule {
    match app-id="pavucontrol"
    open-floating true
}

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

window-rule {
    match app-id="kitty"
    default-column-width { proportion 0.5; }
}

// Picture-in-picture
window-rule {
    match title="Picture-in-Picture"
    open-floating true
}

Use niri msg windows to list open windows and their app-id values. This is essential for writing accurate window rules. The match field supports regex patterns for both app-id and title.

Essential Companion Tools

Niri, like all tiling compositors, does not bundle a bar, launcher, notification daemon, or lock screen. You assemble these from the Wayland ecosystem. Here are the tools we run daily alongside Niri:

• Waybar — Status bar with workspace indicators, system tray, clock, and custom modules. Niri has native Waybar integration for workspace display. Style it with CSS for a consistent look.
• Fuzzel — Lightweight Wayland-native application launcher written in C. Faster than wofi, simpler than rofi. Type to search installed applications and launch them instantly.
• Swaylock or Swaylock-effects — Screen locking. Swaylock-effects adds blur and gradient options for a polished lock screen. Works with Niri without modification.
• Mako or Dunst — Notification daemons. Mako is lighter and more Wayland-native. Dunst has more features and per-application rules. Both work with Niri.
• wl-clipboard — Provides wl-copy and wl-paste commands for clipboard operations. Essential for scripting and terminal workflows.
• Grim + Slurp — Screenshot capture (grim) and region selection (slurp). Niri also has built-in screenshot support via niri msg action screenshot.
• Swaybg or Wpaperd — Wallpaper setters. Swaybg is minimal and static. Wpaperd supports per-monitor wallpapers and timed rotation.
• Swayidle — Idle management daemon for automatic screen locking and DPMS control after configurable timeouts.

On NixOS, you can declare all of these in your system or Home Manager configuration, ensuring every workstation in your team gets the same environment.

NVIDIA GPU Considerations

NVIDIA support in Niri has improved significantly since early 2025. With driver version 555+ and the open kernel modules, Niri runs on NVIDIA GPUs with hardware rendering. Our team runs NVIDIA GPUs for AI workloads on Linux, so we have tested this extensively.

Required Configuration

Add kernel parameters for NVIDIA DRM modesetting:

# NixOS
boot.kernelParams = [ "nvidia_drm.modeset=1" "nvidia_drm.fbdev=1" ];

# GRUB (other distros)
# Add to GRUB_CMDLINE_LINUX in /etc/default/grub:
# nvidia_drm.modeset=1 nvidia_drm.fbdev=1

Set environment variables in your Niri configuration or shell profile:

environment {
    LIBVA_DRIVER_NAME "nvidia"
    GBM_BACKEND "nvidia-drm"
    __GLX_VENDOR_LIBRARY_NAME "nvidia"
    NVD_BACKEND "direct"
}

Known Issues

Suspend/resume: Enable NVIDIA’s video memory preservation to prevent crashes on wake. On NixOS: hardware.nvidia.powerManagement.enable = true;. On other distributions, set options nvidia NVreg_PreserveVideoMemoryAllocations=1 in /etc/modprobe.d/nvidia.conf and enable the nvidia-suspend, nvidia-resume, and nvidia-hibernate systemd services.

Flickering: Usually resolved by confirming that nvidia_drm.modeset=1 is active. Check with cat /sys/module/nvidia_drm/parameters/modeset.

Electron apps: Add --ozone-platform=wayland to Electron application launch flags (VS Code, Slack, Discord) for native Wayland rendering. Without this flag, they run through XWayland, which works but produces blurry text on HiDPI displays.

AMD GPUs require no special configuration. The open-source amdgpu driver and Mesa provide full Wayland support with zero extra steps.

Multi-Monitor Setup

Niri handles multiple monitors through the output configuration block. Each monitor gets its own independent set of workspaces, and each workspace is its own scrollable strip.

output "DP-1" {
    mode "2560x1440@165.000"
    position x=0 y=0
    scale 1.0
}

output "HDMI-A-1" {
    mode "1920x1080@60.000"
    position x=2560 y=0
    scale 1.0
}

output "eDP-1" {
    mode "1920x1080@60.000"
    position x=0 y=0
    scale 1.25
}

Use niri msg outputs to list connected displays and their supported modes. You can move columns between monitors with move-column-to-monitor-left and move-column-to-monitor-right keybindings. Hot-plugging is supported: connect or disconnect a monitor and Niri adjusts the layout automatically.

For laptop users with a docking station, you can configure different output blocks for your built-in display and external monitors. Niri remembers workspace assignments per output name, so your layout restores correctly when you dock and undock.

PTG’s Workflow: Why We Chose Niri for Security Work

Our team evaluated every major Wayland compositor before standardizing on Niri. The decision came down to three factors that matter specifically for cybersecurity and IT infrastructure work.

Wayland isolation. Under X11, any application can capture keystrokes from any other application, take screenshots of any window, and inject synthetic input events. A compromised browser extension under X11 can silently log passwords typed into a terminal on a different workspace. Wayland prevents this by design: clients cannot see other clients’ surfaces or intercept their input. For a firm handling CMMC assessments, HIPAA data, and digital forensics, this is a practical security requirement, not a theoretical one.

Rust memory safety. The compositor is among the most privileged software on a Linux system. It has direct GPU access and handles all display output and input routing. A buffer overflow or use-after-free in a compositor is a potential privilege escalation path. Niri, written in Rust, eliminates these classes of vulnerabilities at the language level. Sway and Hyprland are written in C and C++ respectively, where these bugs are possible despite careful coding practices.

The scrollable workflow. Security work involves many parallel windows: terminals running scans, browsers with documentation and reports, monitoring dashboards, communication tools, and database clients. The scrollable model lets us keep everything on one workspace in a logical sequence rather than splitting it across numbered workspaces. During an assessment, we scroll through our toolchain in order: scope definition, scanning output, evidence capture, report drafting. The spatial arrangement matches the workflow sequence.

If your organization is evaluating Linux desktops for compliance-sensitive work, the combination of Wayland isolation, Rust memory safety, and a compositor that stays out of your way makes Niri worth serious consideration. For guidance on building secure Linux workstations or integrating AI tooling on Linux, our team can help.

Comparison Table: Niri vs Hyprland vs Sway vs GNOME

Frequently Asked Questions

Is Niri stable enough for daily use?

Yes. Our team has run Niri daily on NixOS workstations since mid-2025 without workflow-disrupting crashes. The compositor is pre-1.0, which means breaking changes can occur between releases, but the developer maintains a clear changelog and NixOS’s declarative model makes rollbacks trivial. Stick to tagged releases rather than git HEAD for production workstations.

Can I float windows in Niri?

Yes. Niri supports floating windows alongside the scrollable tiled layout. Toggle floating with a keybinding (toggle-window-floating) or set windows to open floating by default via window rules. Floating windows appear above the tiled strip and can be moved and resized freely with the mouse.

How does screen sharing work?

Screen sharing requires xdg-desktop-portal (with the GNOME or GTK portal backend) and PipeWire. Once configured, Chromium-based browsers, Firefox, and Electron apps can share individual windows or the full screen. Niri implements the wlr-screencopy and xdg-desktop-portal-wlr protocols for compatibility.

Does Niri support touchpad gestures?

Yes. Touchpad gestures are configurable for workspace switching and column scrolling. Three-finger horizontal swipe scrolls between columns, and vertical swipe switches workspaces. These are configured in the input.touchpad section.

Can I use Niri with a tiling-style layout instead of scrollable?

The scrollable model is fundamental to Niri’s design, not an optional mode. If you prefer a fixed tiling grid, Sway or Hyprland will serve you better. However, you can approximate a traditional tiling feel by setting center-focused-column "always" and using maximize-column to fill the screen, toggling between focused full-width views.

How do I switch from Sway or Hyprland?

There is no automated config migration. The mental model is different enough that translating configs line-by-line would not capture Niri’s strengths. Start with the configuration examples in this guide, map your essential keybindings, and spend a few days learning the scroll-based navigation. Most users adapt within a week. The core concepts (workspaces, keybindings, window rules, autostart) transfer directly even though the syntax and paradigm differ.

Getting Started

The fastest path to a working Niri desktop: install Niri and companion tools, place a config.kdl in ~/.config/niri/ using the examples from this guide, log into a TTY, and run niri-session. Spend your first session learning to scroll between columns with Mod+H/L and adjusting column widths with Mod+R. The scrollable model clicks once you stop thinking in workspaces and start thinking in spatial position.

If you are building Linux workstations for your organization and want guidance on compositor selection, NixOS deployment, security hardening, or GPU configuration for AI workloads, contact our team at (919) 348-4912 for a consultation.

About the Author: Craig Petronella is the CEO of Petronella Technology Group, a cybersecurity and IT infrastructure firm in Raleigh, NC. With CMMC-RP, CCNA, CWNE, and DFE certifications and over 30 years in IT, Craig’s team runs NixOS with Niri daily for security research and AI development.

Related Guides

• Tokyo Night Theme Setup Guide -- apply a consistent dark color scheme across Niri, your terminal, and your editor.
• Material Shell for GNOME: Tiling Made Simple -- a GNOME-based tiling alternative if you prefer a traditional desktop foundation.
• Nerd Fonts: Complete Install and Setup Guide -- patched fonts with icons for your status bar and terminal.
• Migrate VMware to Proxmox: Complete Guide -- set up the virtualization layer for your Linux infrastructure.