River

River is a dynamic tiling Wayland compositor. River "upstream" has developed into two different projects:-

v3.23.x v3.22.x v3.21.x

• river-classic, which is an upstream fork of the original River version 0.3, now known under that new name. As of December 2025, it is the only version available on Alpine Linux: it can be downloaded as river-classic from Alpine Linux v3.23 and Edge community repositories, while it retains its legacy name as river in the v3.22 and v3.21 community repositories.
• 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.23 and Edge versions

v3.23.x

# apk add river-classic river-classic-doc

• Under Alpine Linux v3.22 and v3.21

v3.22.x v3.21.x

# apk add river river-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-classic-bash-completion in Alpine Linux v3.23 or Edge community, or river-bash-completion in Alpine Linux v3.22 community repo.

To begin a search for any more packages:-

• If running v3.23 or Edge, try apk search -v river-classic first, or see river-classic*.
• For Alpine Linux v3.22/v3.21, or for a cruder, more generic search regardless of the Alpine Linux version, 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

This material is proposed for merging ... It should be merged with Firefox. (Discuss)

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

See also

• An introduction to River - isaacfreund.com