Open-source project
riverwm/river avatar
riverwm/river

River: a Wayland compositor with no window manager inside

[mirror] A non-monolithic Wayland compositor

4,346 stars171 forksZigLicense varies

At a glance

What is it?
River splits the Wayland compositor from the window manager, so tiling, key bindings and decorations live in a separate process that speaks river-window-management-v1. The price is a two part setup: you compile the compositor from Zig against wlroots 0.20, then you pick a window manager to actually run your session.
Who is it for?
River fits people who want to swap window managers on a running session and read the code of both halves. It does not fit anyone who wants a tiling desktop from one install.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly Zig, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • riverwm/river4,346 ★ · +56
Star history
Repository2026-09-232026-11-15
riverwm/river4.3k4.3k

56 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

River keeps no window management policy of its own

River draws frames and hands every decision about windows to another program. The compositor and the window manager are separate processes, and you choose any window manager that implements the river-window-management-v1 protocol. That split covers a long list of things other compositors build into themselves. Window position and size, pointer and keyboard bindings, focus management, window decorations, desktop shell graphics: each one belongs to the window manager process. What river keeps is frame perfect rendering, support for many Wayland protocol extensions, Xwayland support, and the ability to swap window managers. The code is Zig, and what you install is a compositor that has no opinion about how you want your windows arranged. The stated reasons for the split are a lower barrier to writing a Wayland window manager, and the option of implementing one in a high level garbage collected language without dragging compositor performance and latency down with it.

Hot swapping the window manager without restarting your programs

Because policy lives outside the compositor, changing it does not mean logging out. Hot swapping between window managers without restarting the compositor and all Wayland programs is one of the four reasons given for the design. Programs keep their connections to the display server while a different window manager takes over arranging them. The project also states that the river-window-management-v1 protocol and its other river protocol extensions are stable, and that window managers are not broken, so the window manager you pick is not pinned to a compositor rebuild. tinyrwm is published as an example window manager, which is the fastest way to see how little code has to sit on the other side of that protocol. The wiki holds a list of compatible window managers, and that list, not the compositor binary, is where you shop for tiling behaviour.

Startup runs an executable named init from your config directory

On startup river looks for one specific file. It runs the executable at $XDG_CONFIG_HOME/river/init if such an executable exists, and when $XDG_CONFIG_HOME is not set the path becomes ~/.config/river/init instead.

bash
$XDG_CONFIG_HOME/river/init
~/.config/river/init

There is no config file in a language river parses itself, and no key anywhere that says how windows should be arranged. Usually this executable is a shell script which starts the user's window manager and any other long running programs. Two paths, then the compositor and the rest of your session are your problem. The river(1) man page and the wiki FAQ are the places the startup behaviour is written down.

zig 0.16, wlroots 0.20, and an Xwayland option that is off by default

Building river means compiling Zig against a fixed set of system libraries.

text
zig 0.16
wayland
wayland-protocols
wlroots 0.20
xkbcommon 1.12 or newer
libevdev
pixman
pkg-config
scdoc (optional, but required for man page generation)

Development versions are required where your distribution offers them. The example build installs into a local prefix rather than a system one:

bash
zig build -Doptimize=ReleaseSafe --prefix ~/.local install

Xwayland support is not in that command. It comes from passing the -Dxwayland option as well, and `zig build -h` prints the full option list the build script accepts. Packagers are pointed at PACKAGING.md instead of this command.

Nested for a trial run, KMS/DRM from a tty for the real session

River runs in one of two ways: nested inside an existing X11 or Wayland session, or directly from a tty using KMS/DRM. Running it nested is how you try river without giving up the session you already have, and running it from a tty is the mode that replaces your login session. Either way the command is just the river binary, with no arguments and no flags given in the documentation. What that command does not do is start your window manager for you, because the init executable does that. This is also where the naming question settles: if what you want is the old dynamic tiling version of river, that project is called river-classic and this is not it.

No tiling, no bindings, no decorations: the compositor installs none of them

Read as a division of labour, handing all of that policy to a separate window manager looks like freedom. Read as an install checklist, every one of those features has to be sourced somewhere else before you have a usable desktop. Nothing in the repository stands in as a default window manager, so the wiki list of compatible window managers is where that choice gets made, and a separate page of useful companion software covers the rest of the desktop. For someone setting river up today this means a compositor build, then a window manager, then a bar and a status setup, all decided before the first login. For someone who wants a working session out of one package, the split is overhead with no payoff.

Three licences, SPDX headers, and patches from language models refused

River follows the REUSE Specification, every file carries SPDX copyright and license information, and the LICENSES directory at the top level holds the texts. The split matters in three places. Source code is released under GPL-3.0-only. The Wayland protocols, river-window-management-v1 among them, are MIT, and that is the licence that matters most to anyone writing a window manager, since the protocol definitions can be implemented without taking the compositor's copyleft terms along. The logo and the documentation are CC-BY-SA-4.0. Contributions follow separate rules: ARCHITECTURE.md gives an overview of the code base, CONTRIBUTING.md covers submitting patches, and CODE_OF_CONDUCT.md governs the tracker. The rule that stands out is the strict no LLM, no AI policy. Use of generative AI and LLMs is forbidden for all contributions to river, and that explicitly includes bug reports and comments on the issue tracker.

main moved on 2026-09-23 while the newest tag is still v0.3.0

The branch is current: the last push to this mirror was on 2026-10-30. The release history is not. v0.3.0 was published on 2024-04-16, and it sits above v0.2.6 from 2023-11-25 and v0.2.5 from 2023-11-24, so the newest tag is more than two years behind the code it belongs to. A distribution package may therefore hand you v0.3.0 while the wlroots 0.20 and zig 0.16 lines in the build instructions describe the tip of main. Packagers get separate guidance in PACKAGING.md. The top level layout shows where the work lives: river/ for the compositor, protocol/ for the Wayland protocols, common/ for shared code, plus contrib/, doc/ and build.zig.zon at the root. Check which version your package carries and whether its dependency requirements match your system before you plan a session around it.

Editorial conclusion

River fits people who want to swap window managers on a running session and read the code of both halves. It does not fit anyone who wants a tiling desktop from one install. Verify two things first: which version your distribution actually ships, because the newest tag v0.3.0 was published on 2024-04-16 while the branch moved on 2026-10-30, and whether your system has the dependency versions the build names (wlroots 0.20, xkbcommon 1.12 or newer, zig 0.16).

Frequently asked questions

Does river include a window manager?

No. River does not combine the compositor and the window manager into one program, and it defers all window management policy to a separate window manager implementing the river-window-management-v1 protocol. A list of compatible window managers lives on the project wiki, and tinyrwm is published as an example implementation.

How do I build and install river from source?

Install zig 0.16, wayland, wayland-protocols, wlroots 0.20, xkbcommon 1.12 or newer, libevdev, pixman and pkg-config, then run `zig build -Doptimize=ReleaseSafe --prefix ~/.local install`. Xwayland support is enabled by passing the -Dxwayland option, and `zig build -h` lists all build options.

Where does river look for its configuration?

On startup river runs the executable file at $XDG_CONFIG_HOME/river/init if such an executable exists, and falls back to ~/.config/river/init when $XDG_CONFIG_HOME is not set. That file is usually a shell script which starts the user's window manager and any other long running programs.

What is the difference between river and river-classic?

The old dynamic tiling version of river is a separate project named river-classic. Current river has no built in tiling at all: window position and size, key bindings, focus management and decorations all belong to a separate window manager process.

Can I test river without replacing my current desktop session?

Yes. River can be run nested inside an X11 or Wayland session, or directly from a tty using KMS/DRM, and simply running the river command starts it in the way your session was launched.

Does river accept patches or bug reports written by an AI assistant?

No. Use of generative AI and LLMs is strictly forbidden for all contributions to river, and that includes bug reports and comments on the issue tracker. Submissions go through the process described in CONTRIBUTING.md.

Official sources

  1. Issues
  2. Project website
  3. README
  4. Releases
  5. riverwm/river on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/riverwm-river.svg)](https://hysenlabs.com/projects/riverwm-river)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/riverwm-river.svg)](https://hysenlabs.com/projects/riverwm-river)

Was this useful?