River
River is a dynamic tiling Wayland compositor. River "upstream" has developed into two different projects:-
- river-classic, which is an upstream fork of the original River version 0.3, now known under that new name. As of November 2025, it is the only version available on Alpine Linux: it can be downloaded as river-classic from the edge community repository while it retains its legacy name as river in the Alpine Linux v3.22 and v3.21 community repositories.
v3.22.x v3.21.x
- The current River project upstream, version 0.4+, which is developing under their new river-window-management-v1 protocol, also known by its rwm tag.
Updating the original river package from version 0.3 to version 0.4 would cause breakages, and therefore, distinct projects are being developed upstream.
Prerequisites
- Internet connectivity, unless the packages have been pre-fetched into a local cache.
- Install appropriate Graphics driver drivers for your hardware. Without graphics drivers, errors are likely to occur when starting your desktop.
- A non-root user account with appropriate groups for desktop usage.
- The community repository must be enabled.
- Set up eudev.
- Install and enable D-Bus. Without D-Bus, icons and keyboard shortcuts may be missing.
- Wayland compositors need raw access to input and output devices, typically mediated by a seat manager. Either seatd or elogind work fine, but installing both leads to conflicts.
- Installing wayland-base enables elogind as the seat manager and also enables the community repository and eudev.
Installation
Install river-classic and its documentation:
- Under Alpine Linux v3.22 and v3.21
v3.22.x v3.21.x
- Under Alpine Linux Edge version
# apk add river-classic river-classic-doc
The -doc packages are required to use the example config.
Install your choice of additional packages. The following list includes icons, fonts and a terminal emulator named foot, which is the default in river-classic's sample init file that we will use later.
# apk add adwaita-icon-theme foot font-dejavu
Further packages that are available include the following. Ensure that the edge repository is enabled and tagged first before installing any of the following with the @testing tag, last checked in November 2025:-
- rivercarro for a fork of the rivertile layout (tag as @testing);
- river-luatile to write layouts in lua (tag as @testing);
- river-shifttags to enable the reordering of tags (tag as @testing):
- river-bedload to send info to STDOUT (tag as @testing);
- those for bash/zsh/fish completion (some are in @testing, some in community repo): say, river-bash-completion in Alpine Linux v3.22 community repo, or river-classic-bash-completion in Alpine Linux Edge community;
To begin a search for any more packages:-
- If running Edge, run
apk search -v river-classicfirst, or see river-classic*. - For Alpine Linux v3.22/v3.21, or for a cruder, more generic search, one could try
apk search -v river | grep -v 'driver', which would exclude the term 'driver';apk search -v river; or see river* for packages that begin with that term.
Running river-classic
Before running river-classic for the first time, copy the sample init file to ~/.config:
install -Dm0755 /usr/share/doc/river/examples/init -t ~/.config/river
Set XDG_RUNTIME_DIR and then start river-classic/river with the same instruction:
river
Troubleshooting
 |
The following are a few observations discovered while running river-classic; although not directly related to the compositor, they have been tacked onto the end of this wiki.
Firefox 89.0.1 complained of "glxtest: libpci missing" on launch, resolved with:
apk add pciutils-libs
Firefox 89.0.1 furthermore complained continuously: "Unable to load hand2 from the cursor theme", resolved as follows:
mkdir -p ~/.icons/default ln -s /usr/share/icons/Adwaita/cursors ~/.icons/default/cursors