River is a non-monolithic Wayland compositor. Unlike other Wayland compositors,
river does not combine the compositor and window manager into one program.
Instead, users can choose any window manager implementing the
river-window-management-v1 protocol.
River is packaged by various
Linux distributions as well as FreeBSD. The source code is hosted on
codeberg, which is where the issue tracker
may be found and where contributions are accepted. Read-only mirrors of the
source code exist on sourcehut and
github.
The latest river release can be found here on codeberg.
If you are looking for the old dynamic tiling version of river, see
river-classic.
Features
River defers all window management policy to a separate window manager
implementing the river-window-management-v1
protocol. This includes window position/size, pointer/keyboard bindings, focus
management, window decorations, desktop shell graphics, and more.
River itself provides frame perfect rendering, good performance, support for
many Wayland protocol extensions, robust Xwayland support, the ability to
hot-swap window managers, and more.
Motivation
Why split the window manager to a separate process? I aim to:
Significantly lower the barrier to entry for writing a Wayland window manager.
Allow implementing Wayland window managers in high-level garbage collected
languages without impacting compositor performance and latency.
Allow hot-swapping between window managers without restarting the compositor
and all Wayland programs.
Promote diversity and experimentation in window manager design.
Current Status
The first release supporting the
river-window-management-v1
protocol will be 0.4.0. The protocol is implemented on river’s main branch and is already
robust/feature complete enough for me to use as my daily driver. There are
however missing features that need to be implemented before the 0.4.0 release,
for example input configuration.
Currently the only documentation for the
river-window-management-v1
protocol is the protocol specification itself. While this is all developers comfortable
with writing Wayland clients should need, I’d like to add some more
beginner-friendly documentation including a well-commented example window
manager before the 0.4.0 release.
I would also like to get more feedback on the
river-window-management-v1
protocol before the 0.4.0 release. If you are working on a window manager and have
questions/feedback I’d love to hear from you!
With regards to protocol stability, my goal is to never make a backwards
incompatible change and stay at v1 forever. I’ve been iterating on this
protocol since April 2023 and am quite confident in the design and extensibility
of the current protocol.
If everything goes well with the 0.4.0 release, I expect the following
non-bugfix release to be river 1.0.0. After river 1.0.0, all backwards
incompatible changes will be strictly avoided.
Documentation
The official river documentation is the man pages.
We also have a wiki.
To discuss river and ask questions, join our IRC channel,
#river on irc.libera.chat. Our code
of conduct may be found
here
Donate
If my work on river adds value to your life and you’d like to support me
financially you can find donation information here.