2024-01-17 14:15:05 +03:00
< h1 align = "center" > niri< / h1 >
< p align = "center" > A scrollable-tiling Wayland compositor.< / p >
< p align = "center" >
< a href = "https://matrix.to/#/#niri:matrix.org" > < img alt = "Matrix" src = "https://img.shields.io/matrix/niri%3Amatrix.org?logo=matrix&label=matrix" > < / a >
< a href = "https://github.com/YaLTeR/niri/blob/main/LICENSE" > < img alt = "GitHub License" src = "https://img.shields.io/github/license/YaLTeR/niri" > < / a >
< a href = "https://github.com/YaLTeR/niri/releases" > < img alt = "GitHub Release" src = "https://img.shields.io/github/v/release/YaLTeR/niri?logo=github" > < / a >
< / p >
2023-08-10 13:45:54 +03:00
2024-01-17 14:15:05 +03:00
![](https://github.com/YaLTeR/niri/assets/1794388/16f87a4a-afac-49aa-b3e6-5e6f16c943a9)
2023-08-13 11:46:53 +03:00
2024-01-17 14:15:05 +03:00
## About
Windows are arranged in columns on an infinite strip going to the right.
Opening a new window never causes existing windows to resize.
Every monitor has its own separate window strip.
Windows can never "overflow" onto an adjacent monitor.
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.
## Features
- Scrollable tiling
- Dynamic workspaces like in GNOME
- Built-in screenshot UI
- Monitor screencasting through xdg-desktop-portal-gnome
- Touchpad gesture to switch workspaces
- Configurable layout: gaps, borders, struts, window sizes
- Live-reloading config
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
2024-01-17 14:15:05 +03:00
## Inspiration
2023-08-13 11:46:53 +03:00
2024-01-17 14:15:05 +03:00
Niri is heavily inspired by [PaperWM] which implements scrollable tiling on top of GNOME Shell.
2023-08-13 11:46:53 +03:00
2024-01-17 14:15:05 +03:00
One of the reasons that prompted me to try writing my own compositor is being able to properly separate the monitors.
Being a GNOME Shell extension, PaperWM has to work against Shell's global window coordinate space to prevent windows from overflowing.
2023-08-13 11:46:53 +03:00
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
2024-01-06 07:33:12 +03:00
> [!TIP]
> For Fedora users, there's a COPR with built and packaged niri: https://copr.fedorainfracloud.org/coprs/yalter/niri/
>
2024-01-11 09:43:46 +03:00
> For NixOS users, check out https://github.com/sodiboo/niri-flake
2023-11-26 21:02:17 +03:00
2023-11-12 19:19:44 +03:00
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
2024-01-18 10:15:48 +03:00
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 libpango1.0-dev
2023-11-12 19:19:44 +03:00
```
- Fedora:
```sh
2024-01-18 10:15:48 +03:00
sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel clang
2023-11-12 19:19:44 +03:00
```
Next, build niri with `cargo build --release` .
2024-01-11 09:43:46 +03:00
### 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
```
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/` |
2023-11-25 10:01:23 +03:00
| `resources/niri-shutdown.target` | `/usr/lib/systemd/user/` |
2023-11-09 20:37:07 +03:00
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-11-27 07:45:30 +03:00
A step-by-step process for this is explained [on the wiki ](https://github.com/YaLTeR/niri/wiki/Example-systemd-Setup ).
2023-08-27 16:21:21 +03:00
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
2024-01-19 18:01:56 +03:00
[This wiki page ](https://github.com/YaLTeR/niri/wiki/Important-Software ) explains how to run important software required for normal desktop use, including portals.
2023-12-24 18:41:23 +03:00
### Xwayland
See [the wiki page ](https://github.com/YaLTeR/niri/wiki/Xwayland ) to learn how to use Xwayland with niri.
2024-01-17 09:38:32 +03:00
### IPC
You can communicate with the running niri instance over an IPC socket.
Check `niri msg --help` for available commands.
The `--json` flag prints the response in JSON, rather than formatted.
For example, `niri msg --json outputs` .
For programmatic access, check the [niri-ipc sub-crate ](./niri-ipc/ ) which defines the types.
The communication over the IPC socket happens in JSON.
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 |
| ------ | ----------- |
2024-01-18 18:20:46 +03:00
| < kbd > Mod< / kbd > < kbd > Shift< / kbd > < kbd > /< / kbd > | Show a list of important niri hotkeys |
2023-11-25 13:36:42 +03:00
| < kbd > Mod</ kbd >< kbd > T</ kbd > | Spawn `alacritty` (terminal) |
| < kbd > Mod</ kbd >< kbd > D</ kbd > | Spawn `fuzzel` (application launcher) |
| < kbd > Mod</ kbd >< kbd > Alt</ kbd >< kbd > L</ kbd > | Spawn `swaylock` (screen locker) |
2023-08-13 11:46:53 +03:00
| < 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-12-29 07:05:43 +03:00
| < kbd > Mod< / kbd > < kbd > Home< / kbd > and < kbd > Mod< / kbd > < kbd > End< / kbd > | Focus the first or the last column |
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > Home< / kbd > and < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > End< / kbd > | Move the focused column to the very start or to the very end |
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 |
2024-01-15 09:46:53 +03:00
| < 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 column 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 |
2024-01-15 09:46:53 +03:00
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > U< / kbd > or < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > PageDown< / kbd > | Move the focused column 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 column to the workspace above |
2023-09-18 20:06:47 +03:00
| < kbd > Mod< / kbd > < kbd > 1< / kbd > – < kbd > 9< / kbd > | Switch to a workspace by index |
2024-01-15 09:46:53 +03:00
| < kbd > Mod< / kbd > < kbd > Ctrl< / kbd > < kbd > 1< / kbd > – < kbd > 9< / kbd > | Move the focused column 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-11-13 18:08:29 +03:00
| < kbd > Mod< / kbd > < kbd > C< / kbd > | Center column within view |
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.
2024-01-16 19:28:46 +03:00
Niri will live-reload most of the configuration settings, like key binds or gaps or output modes, as you change the config file.
2023-11-25 09:31:16 +03:00
2024-01-17 14:15:05 +03:00
## Contact
We have a Matrix chat, feel free to join and ask a question: https://matrix.to/#/#niri:matrix.org
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