The easiest way to get niri is to install one of the distribution packages.
Here are some of them: [Fedora COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri/) and [nightly COPR](https://copr.fedorainfracloud.org/coprs/yalter/niri-git/) (which I maintain myself), [NixOS Flake](https://github.com/sodiboo/niri-flake), and some more from repology below.
See the [Building](#building) section if you'd like to compile niri yourself.
[](https://repology.org/project/niri/versions)
After installing, start niri from your display manager like GDM.
Press SuperT to run a terminal ([Alacritty]) and SuperD to run an application launcher ([fuzzel]).
To exit niri, press SuperShiftE.
If you're not using a display manager, you should run `niri-session` (systemd) or `niri --session` (not systemd) from a TTY.
The `--session` flag will make niri import its environment variables globally into systemd and D-Bus, and start its D-Bus services.
You can also run `niri` inside an existing desktop session.
Then it will open as a window, where you can give it a try.
Note that this windowed mode is mainly meant for development, so it is a bit buggy (in particular, there are issues with hotkeys).
Next, see the [list of important software](./Important-Software.md) required for normal desktop use, like a notification daemon and portals.
Also, check the [configuration overview](./Configuration:-Overview.md) page to get started configuring niri.
There you can find links to other pages containing thorough documentation and examples for all options.
Finally, the [Xwayland](./Xwayland.md) page explains how to run X11 applications on niri.
### NVIDIA
NVIDIA GPUs tend to have problems running niri (for example, the screen remains black upon starting from a TTY).
Sometimes, the problems can be fixed.
You can try the following:
1. Update NVIDIA drivers. You need a GPU and drivers recent enough to support GBM.
2. Make sure kernel modesetting is enabled. This usually involves adding `nvidia-drm.modeset=1` to the kernel command line. Find and follow a guide for your distribution. Guides from other Wayland compositors can help.
If niri runs but the screen flickers, try adding this into your niri config:
```
debug {
wait-for-frame-completion-before-queueing
}
```
### Asahi, ARM, and other kmsro devices
On some of these systems, niri fails to correctly detect the primary render device.
If you're getting a black screen when starting niri on a TTY, you can try to set the device manually.
First, find which devices you have:
```
$ ls -l /dev/dri/
drwxr-xr-x@ - root 14 мая 07:07 by-path
crw-rw----@ 226,0 root 14 мая 07:07 card0
crw-rw----@ 226,1 root 14 мая 07:07 card1
crw-rw-rw-@ 226,128 root 14 мая 07:07 renderD128
crw-rw-rw-@ 226,129 root 14 мая 07:07 renderD129
```
You will likely have one `render` device and two `card` devices.
Open the niri config file at `~/.config/niri/config.kdl` and put your `render` device path like this:
```
debug {
render-drm-device "/dev/dri/renderD128"
}
```
Save, then try to start niri again.
If you still get a black screen, try using each of the `card` devices.
### Nix/NixOS
There's a common problem of mesa drivers going out of sync with niri, so make sure your system mesa version matches the niri mesa version.
Also, on Intel graphics, you may need a workaround described [here](https://nixos.wiki/wiki/Intel_Graphics).
### Virtual Machines
To run niri in a VM, make sure to enable 3D acceleration.
## Default Hotkeys
When running on a TTY, the Mod key is Super.
When running in a window, the Mod key is Alt.
The general system is: if a hotkey switches somewhere, then adding Ctrl will move the focused window or column there.
| Hotkey | Description |
| ------ | ----------- |
| ModShift/ | Show a list of important niri hotkeys |
| ModT | Spawn `alacritty` (terminal) |
| ModD | Spawn `fuzzel` (application launcher) |
| ModAltL | Spawn `swaylock` (screen locker) |
| ModQ | Close the focused window |
| ModH or Mod← | Focus the column to the left |
| ModL or Mod→ | Focus the column to the right |
| ModJ or Mod↓ | Focus the window below in a column |
| ModK or Mod↑ | Focus the window above in a column |
| ModCtrlH or ModCtrl← | Move the focused column to the left |
| ModCtrlL or ModCtrl→ | Move the focused column to the right |
| ModCtrlJ or ModCtrl↓ | Move the focused window below in a column |
| ModCtrlK or ModCtrl↑ | Move the focused window above in a column |
| ModHome and ModEnd | Focus the first or the last column |
| ModCtrlHome and ModCtrlEnd | Move the focused column to the very start or to the very end |
| ModShiftHJKL or ModShift←↓↑→ | Focus the monitor to the side |
| ModCtrlShiftHJKL or ModCtrlShift←↓↑→ | Move the focused column to the monitor to the side |
| ModU or ModPageDown | Switch to the workspace below |
| ModI or ModPageUp | Switch to the workspace above |
| ModCtrlU or ModCtrlPageDown | Move the focused column to the workspace below |
| ModCtrlI or ModCtrlPageUp | Move the focused column to the workspace above |
| Mod1–9 | Switch to a workspace by index |
| ModCtrl1–9 | Move the focused column to a workspace by index |
| ModShiftU or ModShiftPageDown | Move the focused workspace down |
| ModShiftI or ModShiftPageUp | Move the focused workspace up |
| Mod, | Consume the window to the right into the focused column |
| Mod. | Expel the focused window into its own column |
| ModR | Toggle between preset column widths |
| ModF | Maximize column |
| ModC | Center column within view |
| Mod- | Decrease column width by 10% |
| Mod= | Increase column width by 10% |
| ModShift- | Decrease window height by 10% |
| ModShift= | Increase window height by 10% |
| ModShiftF | Toggle full-screen on the focused window |
| PrtSc | Take an area screenshot. Select the area to screenshot with mouse, then press Space to save the screenshot, or Escape to cancel |
| AltPrtSc | Take a screenshot of the focused window to clipboard and to `~/Pictures/Screenshots/` |
| CtrlPrtSc | Take a screenshot of the focused monitor to clipboard and to `~/Pictures/Screenshots/` |
| ModShiftE | Exit niri |
## Building
First, install the dependencies for your distribution.
- Ubuntu 23.10:
```sh
sudo apt-get install -y gcc clang libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-dev libpango1.0-dev
```
- Fedora:
```sh
sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel clang
```
Next, get latest stable Rust: https://rustup.rs/
Then, build niri with `cargo build --release`.
Check Cargo.toml for a list of build features.
For example, you can replace systemd integration with dinit integration using `cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast`.
> [!WARNING]
> Do NOT build with `--all-features`!
>
> Some features are meant only for development use.
> For example, one of the features enables collection of profiling data into a memory buffer that will grow indefinitely until you run out of memory.
### NixOS/Nix
We have a community-maintained flake which provides a devshell with required dependencies. Use `nix build` to build niri, and then run `./results/bin/niri`.
If you're not on NixOS, you may need [NixGL](https://github.com/nix-community/nixGL) to run the resulting binary:
```
nix run --impure github:guibou/nixGL -- ./results/bin/niri
```
### Packaging
The recommended way to package niri is so that it runs as a standalone desktop session.
To do that, put files into the correct directories according to this table.
| File | Destination |
| ---- | ----------- |
| `target/release/niri` | `/usr/bin/` |
| `resources/niri-session` | `/usr/bin/` |
| `resources/niri.desktop` | `/usr/share/wayland-sessions/` |
| `resources/niri-portals.conf` | `/usr/share/xdg-desktop-portal/` |
| `resources/niri.service` | `/usr/lib/systemd/user/` |
| `resources/niri-shutdown.target` | `/usr/lib/systemd/user/` |
Doing this will make niri appear in GDM and other display managers.
### Manual Installation
If installing directly without a package, the recommended file destinations are slightly different.
In this case, put the files in the directories indicated in the table below.
These may vary depending on your distribution.
| File | Destination |
| ---- | ----------- |
| `target/release/niri` | `/usr/local/bin/` |
| `resources/niri-session` | `/usr/local/bin/` |
| `resources/niri.desktop` | `/usr/local/share/wayland-sessions/` |
| `resources/niri-portals.conf` | `/usr/local/share/xdg-desktop-portal/` |
| `resources/niri.service` | `/etc/systemd/user/` |
| `resources/niri-shutdown.target` | `/etc/systemd/user/` |
[Alacritty]: https://github.com/alacritty/alacritty
[fuzzel]: https://codeberg.org/dnkl/fuzzel