#+TITLE: Niri, btw
#+AUTHOR: Tony, btw
#+date: 2025-11-05
#+HUGO_TITLE: Niri, btw!
#+HUGO_FRONT_MATTER_FORMAT: yaml
#+HUGO_CUSTOM_FRONT_MATTER: :image "/img/niri.png" :showTableOfContents true
#+HUGO_BASE_DIR: ~/repos/tonybtw.com
#+HUGO_SECTION: tutorial/niri
#+EXPORT_FILE_NAME: index
#+OPTIONS: toc:nil broken-links:mark
#+HUGO_AUTO_SET_HEADLINE_SECTION: nil
#+DESCRIPTION: This is a quick and painless tutorial on how to setup Niri on Arch/NixOS/Gentoo. It is a wonderful wayland compositor masquerading as a window manager.

* Intro

What's up guys, my name is Tony, and today I'm gonna give you a quick and painless guide on installing and configuring Niri.

Niri is a "scrollable-tiling" wayland compositor that masquerades as a window manager. Here are some of the unique features of niri:

- Infinite horizontal Scroll
- Dynamic workspaces like in GNOME
- An Overview that zooms out workspaces and windows
- Built-in screenshot UI
- Per Monitor Workspaces (Shoutout to The Linux Cast because I know he loves that so much, and he loves xwayland-sattelite.)
- and much more.

A quote from the famous philosopher, Argocrates:
#+begin_quote
"Niri is the anti-window manager. I can just constantly spawn new windows, without having to worry about my window manager trying to "manage" my windows layout against a set output size. The only downside is that sometimes I forget I have 300 terminals opened all the way to the right."
#+end_quote

Let's jump into the installation.

* Install Dependencies for Niri

Alright so I'm on arch linux, btw, but this is going to work on NixOS, Gentoo, LFS, etc. I'll leave install instructions for all 3 of those distributions in this written guide in a link below the subscribe button.

For arch, here are the dependencies we need to install:

[[https://github.com/YaLTeR/niri][Github Repo]]

*** Arch Linux
#+begin_src sh
yay -S niri noctalia-shell
#+end_src

*** NixOS
For NixOS, you can add niri to your system configuration. Here's how to enable it:

#+begin_src nix
# In your configuration.nix or flake.nix
{
  programs.niri.enable = true;

  # Or add to your packages
  environment.systemPackages = with pkgs; [
    niri
    xwayland-satellite
  ];
}
#+end_src

For noctalia-shell on NixOS, you'll need to add it as a flake input (see the noctalia-shell section below for details).

*** Gentoo
For Gentoo, niri can be installed from GURU overlay:

#+begin_src sh
# Add the GURU overlay
sudo eselect repository enable guru
sudo emerge --sync guru

# Install niri
sudo emerge gui-wm/niri
#+end_src

We're going to use Noctalia Shell today as a bar, because I've used waybar for all of my previous wayland videos, I wanted to shake things up a bit. I'll do more of a deep dive on Quickshell in a separate video, but for today we're going to focus on Niri and how to customize and utilize it.

** Requirements for Niri
- glibc
- wayland
- wayland-protocols
- libinput
- libdrm
- libxkbcommon
- pixman
- git
- meson
- ninja
- libdisplay-info
- libliftoff
- hwdata
- seatd
- pcre2

** Extra stuff for my setup today:
- alacritty (terminal emulator)
- fuzzel (a dmenu clone for wayland)
- swaybg (for wallpapers)
- firefox (web browser)
- ttf-jetbrains-mono-nerd (font)
- xwayland-sattelite

So let's install these with pacman -Sy
#+begin_src sh
sudo pacman -Sy alacritty fuzzel swaybg firefox ttf-jetbrains-mono-nerd xwayland-sattelite
#+end_src

Alright, lets jump into niri by typing 'Niri'

* Load Niri
We're in niri now by and as you can see, this awesome help tool reminds you of the default kebinds. You can open this at any time with super shift slash.

So lets hit Super + T to open alacritty, by defualt.

Open up .config/niri/config.kdl, and lets change a few keybinds, and options.

First, lets add this option to the top of the file:

#+begin_src kdl
prefer-no-csd
#+end_src

This flag will make niri ask the applications to omit their client-side decorations, so we won't see this header on alacritty.

As always, let's fix the repeat rate and repeat delay, heres how to do it in niri:

#+begin_src kdl
input {
    keyboard {
        repeat-delay 200
        repeat-rate 35
    }
}
#+end_src

For touchpad settings, this is up to you, I prefer 'natural-scroll' off, but I'll leave all these options commented out in my config so you guys can adjust them as needed for your preferences.

And let's uncomment this so our focus follows our mouse:

#+begin_src kdl
focus-follows-mouse max-scroll-amount="0%"
#+end_src

Let's add some keybinds here:
#+begin_src kdl
    Mod+Return hotkey-overlay-title="Open a Terminal: alacritty" { spawn "alacritty"; }
    Mod+D hotkey-overlay-title="Run an Application: fuzzel" { spawn "fuzzel"; }

    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; }
    Mod+Shift+6 { move-column-to-workspace 6; }
    Mod+Shift+7 { move-column-to-workspace 7; }
    Mod+Shift+8 { move-column-to-workspace 8; }
    Mod+Shift+9 { move-column-to-workspace 9; }
#+end_src

And lets change control to shift here as well for moving things to separate workspaces.

Now for the layout section, let's customize the gaps and focus ring:

#+begin_src kdl
layout {
    gaps 5

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

    border {
        off
    }
}
#+end_src

I also like to add some rounded corners to my windows with window rules:

#+begin_src kdl
window-rule {
    geometry-corner-radius 4
    clip-to-geometry true
}
#+end_src

This is about 90% complete, and thats because the defaults for niri are already really good imo. If you have multiple monitors, you need to edit the monitors block, and you can get information about your monitors with `niri msg outputs`

The file reloads automatically so we can test opening another terminal here, and boom there we go.

Alright this is nice, but we can do better. I personally could get by just like this, but lets add that noctalia shell.

* Noctalia Shell + Autostart
So for noctalia shell, we've already installed it with yay if you're on Arch. Here are the instructions for all distributions:

*** Arch Linux
#+begin_src sh
yay -S noctalia-shell
#+end_src

*** NixOS
For NixOS, noctalia-shell needs to be added as a flake input. Add this to your flake.nix:

#+begin_src nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    noctalia-shell.url = "github:Noctalia-Shell/noctalia-shell";
  };

  outputs = { self, nixpkgs, noctalia-shell }: {
    nixosConfigurations.yourHostname = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        ({ pkgs, ... }: {
          environment.systemPackages = [
            noctalia-shell.packages.x86_64-linux.default
          ];
        })
      ];
    };
  };
}
#+end_src

*** Gentoo
For Gentoo, noctalia-shell can be compiled from source:

#+begin_src sh
# Install quickshell first (dependency)
git clone https://github.com/outfoxxed/quickshell
cd quickshell
# Follow the build instructions in their README

# Then install noctalia-shell
git clone https://github.com/Noctalia-Shell/noctalia-shell
# Copy the config to ~/.config/quickshell/noctalia
#+end_src

Lets test to see if we have access to noctalia shell by typing:

`noctalia-shell`
`qs -c ~/.config/quickshell/noctalia`

So lets add this to our spawn-at-startup!

#+begin_src kdl
spawn-at-startup "noctalia-shell"
#+end_src

Noctalia-shell is highly customizable. Here are some of my settings that you can adjust in `~/.config/quickshell/noctalia/settings.json`:

#+begin_src json
{
    "bar": {
        "position": "top",
        "widgets": {
            "left": [
                { "id": "SystemMonitor", "showCpuTemp": true, "showCpuUsage": true, "showMemoryUsage": true },
                { "id": "ActiveWindow", "showIcon": true, "maxWidth": 145 },
                { "id": "MediaMini", "maxWidth": 145 }
            ],
            "center": [
                { "id": "Workspace", "labelMode": "name", "hideUnoccupied": false }
            ],
            "right": [
                { "id": "ScreenRecorder" },
                { "id": "Tray" },
                { "id": "Battery" },
                { "id": "Volume" },
                { "id": "Clock", "formatHorizontal": "HH:mm ddd, MMM dd" },
                { "id": "ControlCenter" }
            ]
        }
    },
    "colorSchemes": {
        "darkMode": true,
        "predefinedScheme": "Tokyo Night"
    },
    "ui": {
        "fontDefault": "JetBrainsMono Nerd Font Propo"
    }
}
#+end_src

The color scheme is in `~/.config/quickshell/noctalia/colors.json`, and I'm using a Tokyo Night theme.


* Wallpaper
Actually, if you're using noctalia-shell, wallpaper management is built right in! Noctalia has a wallpaper selector and can automatically rotate through your wallpapers.

In your `~/.config/quickshell/noctalia/settings.json`, configure the wallpaper settings:

#+begin_src json
{
    "wallpaper": {
        "directory": "/home/tony/walls",
        "enabled": true,
        "fillMode": "crop",
        "randomEnabled": true,
        "randomIntervalSec": 300,
        "transitionDuration": 1500
    }
}
#+end_src

This will automatically handle your wallpapers with smooth transitions. But if you want to use swaybg manually, you can still add it to your niri config:

#+begin_src kdl
spawn-sh-at-startup "swaybg -i ~/walls/wall1.png"
#+end_src

* Screenshot Script
Good news! Niri has a built-in screenshot UI that's actually really nice. You can trigger it with these keybinds (already in the default config):

#+begin_src kdl
Mod+S { screenshot; }
Ctrl+Print { screenshot-screen; }
Alt+Print { screenshot-window; }
#+end_src

Screenshots are saved to `~/Pictures/Screenshots/` by default, but you can change this in your config:

#+begin_src kdl
screenshot-path "~/Pictures/Screenshots/Screenshot from %Y-%m-%d %H-%M-%S.png"
#+end_src

If you prefer the traditional grim + slurp workflow, you can still use that:

#+begin_src sh
#!/bin/sh
grim -g "$(slurp)" - | wl-copy
#+end_src

And bind it in your config.kdl:

#+begin_src kdl
Mod+Shift+S { spawn "path-to-your-screenshot-script"; }
#+end_src

* Additional Customizations
So at this point, the world is really your oyster. Niri is incredibly flexible and customizable.

Here's a summary of my favorite keybinds:

| Keybind             | Action                              |
|---------------------+-------------------------------------|
| Super+Return        | Opens a terminal (alacritty)        |
| Super+D             | Runs fuzzel (application launcher)  |
| Super+Q             | Closes a window                     |
| Super+H/J/K/L       | Navigate between windows (vim-style)|
| Super+1-9           | Switch to workspace 1-9             |
| Super+Shift+1-9     | Move window to workspace 1-9        |
| Super+S             | Take a screenshot                   |
| Super+O             | Toggle Overview mode                |
| Super+F             | Maximize column                     |
| Super+Shift+F       | Fullscreen window                   |
| Super+R             | Cycle through preset column widths  |
| Super+C             | Center the current column           |

Some advanced features I really like:

Named workspaces - You can create custom named workspaces instead of just numbers:

#+begin_src kdl
workspace "a" { }
workspace "b" { }
workspace "c" { }
#+end_src

Window rules - Automatically manage specific applications:

#+begin_src kdl
window-rule {
    match title="Firefox"
    open-on-workspace "c"
    open-maximized true
}
#+end_src

The Overview feature (Super+O) is absolutely killer - it gives you a birds-eye view of all your workspaces and windows, similar to GNOME's Activities view.

* Final Thoughts

You're now ready to use Niri as a modern, fast, and extensible wayland compositor.

Thanks so much for checking out this tutorial. If you got value from it, and you want to find more tutorials like this, check out
my youtube channel here: [[https://youtube.com/@tony-btw][YouTube]], or my website here: [[https://www.tonybtw.com][tony,btw]]

You can support me here: [[https://ko-fi.com/tonybtw][kofi]]