2023-08-10 13:45:54 +03:00
# niri
2023-09-26 13:34:26 +03:00
A scrollable-tiling Wayland compositor.
2023-08-13 11:46:53 +03:00
2023-09-26 13:34:26 +03:00
![](https://github.com/YaLTeR/niri/assets/1794388/e35fd9e1-105b-4bd5-94c9-207fd6fb3c18)
2023-08-14 18:05:57 +03:00
2023-08-13 11:46:53 +03:00
## Status
2023-10-24 13:33:26 +03:00
A lot of the essential functionality is implemented, plus some goodies on top.
Feel free to give niri a try.
Have your waybars and fuzzels ready: niri is not a complete desktop environment.
2023-08-13 11:46:53 +03:00
2023-10-31 20:07:11 +03:00
https://github.com/YaLTeR/niri/assets/1794388/5d355694-7b06-4f00-8920-8dce54a8721c
2023-08-14 18:05:57 +03:00
2023-08-13 11:46:53 +03:00
## Idea
Niri implements scrollable tiling, heavily inspired by [PaperWM].
Windows are arranged in columns on an infinite strip going to the right.
2023-08-27 16:21:21 +03:00
Every column takes up a full monitor worth of height, divided among its windows.
2023-08-13 11:46:53 +03:00
With multiple monitors, every monitor has its own separate window strip.
2023-08-27 16:21:21 +03:00
Windows can never "overflow" onto an adjacent monitor.
2023-08-13 11:46:53 +03:00
This is one of the reasons that prompted me to try writing my own compositor.
2023-10-03 11:31:05 +03:00
PaperWM is a solid implementation, but, being a GNOME Shell extension, it has to work around Shell's global window coordinate space to prevent windows from overflowing.
2023-08-13 11:46:53 +03:00
Niri also has dynamic workspaces which work similar to GNOME Shell.
Since windows go left-to-right horizontally, workspaces are arranged vertically.
Every monitor has an independent set of workspaces, and there's always one empty workspace present all the way down.
Niri tries to preserve the workspace arrangement as much as possible upon disconnecting and connecting monitors.
2023-08-27 16:21:21 +03:00
When a monitor disconnects, its workspaces will move to another monitor, but upon reconnection they will move back to the original monitor.
2023-08-10 13:45:54 +03:00
2023-11-12 19:19:44 +03:00
## Building
First, install the dependencies for your distribution.
- Ubuntu:
```sh
sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:pipewire-debian/pipewire-upstream
sudo apt-get update -y
sudo apt-get install -y libudev-dev libgbm-dev libxkbcommon-dev libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev libseat-dev libpipewire-0.3-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 clang
```
Next, build niri with `cargo build --release` .
2023-11-09 20:37:07 +03:00
## Installation
The recommended way to install and run niri is 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/` |
Doing this will make niri appear in GDM and, presumably, other display managers.
2023-08-10 13:45:54 +03:00
## Running
2023-10-03 11:31:05 +03:00
`cargo run --release`
2023-08-10 13:45:54 +03:00
2023-11-09 20:37:07 +03:00
Inside an existing desktop session, it will run in a window.
2023-08-13 11:46:53 +03:00
On a TTY, it will run natively.
To exit when running on a TTY, press < kbd > Super< / kbd > < kbd > Shift< / kbd > < kbd > E< / kbd > .
2023-08-27 16:21:21 +03:00
### Session
2023-11-09 20:37:07 +03:00
If you followed the recommended installation steps above, niri should appear in your display manager.
Starting it from there will run niri as a desktop session.
2023-08-27 16:21:21 +03:00
The niri session will autostart apps through the systemd xdg-autostart target.
You can also autostart systemd services like [mako] by symlinking them into `$HOME/.config/systemd/user/niri.service.wants/` .
2023-10-03 11:31:05 +03:00
Niri also works with some parts of xdg-desktop-portal-gnome.
In particular, it supports file choosers and monitor screencasting (e.g. to [OBS]).
2023-08-27 16:21:21 +03:00
2023-09-05 11:58:51 +03:00
## Default Hotkeys
2023-08-13 11:46:53 +03:00
When running on a TTY, the Mod key is < kbd > Super< / kbd > .
When running in a window, the Mod key is < kbd > Alt< / kbd > .
The general system is: if a hotkey switches somewhere, then adding < kbd > Ctrl< / kbd > will move the focused window or column there.
| Hotkey | Description |
| ------ | ----------- |
| < kbd > Mod</ kbd >< kbd > T</ kbd > | Spawn `alacritty` |
| < kbd > Mod< / kbd > < kbd > Q< / kbd > | Close the focused window |
2023-09-05 11:58:51 +03:00
| < kbd > Mod< / kbd > < kbd > H< / kbd > or < kbd > Mod< / kbd > < kbd > ←< / kbd > | Focus the column to the left |
| < kbd > Mod< / kbd > < kbd > L< / kbd > or < kbd > Mod< / kbd > < kbd > →< / kbd > | Focus the column to the right |
2023-08-13 11:46:53 +03:00
| < kbd > Mod< / kbd > < kbd > J< / kbd > or < kbd > Mod< / kbd > < kbd > ↓< / kbd > | Focus the window below in a column |
| < kbd > Mod< / kbd > < kbd > K< / kbd > or < kbd > Mod< / kbd > < kbd > ↑< / kbd > | Focus the window above in a column |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > H< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > ←< / kbd > | Move the focused column to the left |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > L< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > →< / kbd > | Move the focused column to the right |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > J< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > ↓< / kbd > | Move the focused window below in a column |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > K< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > ↑< / kbd > | Move the focused window above in a column |
2023-08-16 07:03:20 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > H< / kbd > < kbd > J< / kbd > < kbd > K< / kbd > < kbd > L< / kbd > or < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > ←< / kbd > < kbd > ↓< / kbd > < kbd > ↑< / kbd > < kbd > →< / kbd > | Focus the monitor to the side |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > Shift< / kbd > < kbd > H< / kbd > < kbd > J< / kbd > < kbd > K< / kbd > < kbd > L< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > Shift< / kbd > < kbd > ←< / kbd > < kbd > ↓< / kbd > < kbd > ↑< / kbd > < kbd > →< / kbd > | Move the focused window to the monitor to the side |
2023-09-18 20:06:47 +03:00
| < kbd > Mod< / kbd > < kbd > U< / kbd > or < kbd > Mod< / kbd > < kbd > PageDown< / kbd > | Switch to the workspace below |
| < kbd > Mod< / kbd > < kbd > I< / kbd > or < kbd > Mod< / kbd > < kbd > PageUp< / kbd > | Switch to the workspace above |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > U< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > PageDown< / kbd > | Move the focused window to the workspace below |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > I< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > PageUp< / kbd > | Move the focused window to the workspace above |
| < kbd > Mod< / kbd > < kbd > 1< / kbd > – < kbd > 9< / kbd > | Switch to a workspace by index |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > 1< / kbd > – < kbd > 9< / kbd > | Move the focused window to a workspace by index |
2023-10-14 19:48:45 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > U< / kbd > or < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > PageDown< / kbd > | Move the focused workspace down |
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > I< / kbd > or < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > PageUp< / kbd > | Move the focused workspace up |
2023-08-13 11:46:53 +03:00
| < kbd > Mod< / kbd > < kbd > ,< / kbd > | Consume the window to the right into the focused column |
| < kbd > Mod< / kbd > < kbd > .< / kbd > | Expel the focused window into its own column |
2023-08-14 17:36:46 +03:00
| < kbd > Mod< / kbd > < kbd > R< / kbd > | Toggle between preset column widths |
| < kbd > Mod< / kbd > < kbd > F< / kbd > | Maximize column |
2023-10-03 11:31:05 +03:00
| < kbd > Mod< / kbd > < kbd > -< / kbd > | Decrease column width by 10% |
| < kbd > Mod< / kbd > < kbd > =< / kbd > | Increase column width by 10% |
2023-11-08 18:14:12 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > -< / kbd > | Decrease window height by 10% |
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > =< / kbd > | Increase window height by 10% |
2023-08-16 08:31:36 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > F< / kbd > | Toggle full-screen on the focused window |
2023-10-30 19:55:46 +03:00
| < kbd > PrtSc< / kbd > | Take an area screenshot. Select the area to screenshot with mouse, then press Space to save the screenshot, or Escape to cancel |
2023-10-10 11:50:17 +03:00
| < kbd > Alt</ kbd >< kbd > PrtSc</ kbd > | Take a screenshot of the focused window to clipboard and to `~/Pictures/Screenshots/` |
2023-10-30 19:55:46 +03:00
| < kbd > Ctrl</ kbd >< kbd > PrtSc</ kbd > | Take a screenshot of the focused monitor to clipboard and to `~/Pictures/Screenshots/` |
2023-09-03 10:34:38 +03:00
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > Shift< / kbd > < kbd > T< / kbd > | Toggle debug tinting of rendered elements |
2023-08-13 11:46:53 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > E< / kbd > | Exit niri |
2023-08-10 13:45:54 +03:00
2023-09-05 11:58:51 +03:00
## Configuration
Niri will load configuration from `$XDG_CONFIG_HOME/.config/niri/config.kdl` or `~/.config/niri/config.kdl` .
If this fails, it will load [the default configuration file ](resources/default-config.kdl ).
Please use the default configuration file as the starting point for your custom configuration.
2023-08-13 11:46:53 +03:00
[PaperWM]: https://github.com/paperwm/PaperWM
2023-08-27 16:21:21 +03:00
[mako]: https://github.com/emersion/mako
2023-10-03 11:31:05 +03:00
[OBS]: https://flathub.org/apps/com.obsproject.Studio
2023-08-10 13:45:54 +03:00