The following USE flags are available:
River is currently only available in the wayland-desktop ebuild repository. After activating the overlay, install by:
emerge --ask gui-wm/river
River is mainly configured through the riverctl function. To see documentation for river and configuration options:
Layouts are managed by rivertile. To see configuration options:
River starts by executing the init file. By default, river will look for the init file at $XDG_CONFIG_HOME/river/init. If $XDG_CONFIG_HOME is not set, river will search for the init file at ~/.config/river/init. Make sure to create an init file before running river. A default is provided by the authors at .
Per the authors, the init file can be any executable script, not just shell scripts. See an example written in lua5.4 .
River does not have a built-in status bar. gui-apps/waybar has modules for showing river tags:
emerge --ask gui-apps/waybar
The authors also recommended the following status bars:
- yambar: gui-apps/waybar
- levee: 
- i3bar-river: 
dev-libs/light can be used to adjust backlight and brightness. Here is an example config:
riverctl map $mode None XF86MonBrightnessUp spawn 'light -A 5' riverctl map $mode None XF86MonBrightnessDown spawn 'light -U 5'
The following configuration can be used for changing sound volume with amixer:
riverctl map $mode None XF86AudioRaiseVolume spawn 'amixer set "Master" 10%+' riverctl map $mode None XF86AudioLowerVolume spawn 'amixer set "Master" 10%-' riverctl map $mode None XF86AudioMute spawn 'amixer set "Master" toggle'
Alternatively, if pulseaudio is being used, the following configuration should also work:
riverctl map $mode None XF86AudioRaiseVolume spawn 'pactl set-sink-volume @DEFAULT_SINK@ +5%' riverctl map $mode None XF86AudioLowerVolume spawn 'pactl set-sink-volume @DEFAULT_SINK@ -5%'
See the Sway article for more information.
Setting a wallpaper
The wallpaper can be set with swaybg with a command like this:
swaybg -m fill -i /home/larry/wallpapers/Awesome_Gentoo_Wallpaper.png &
River can be started from a tty or a terminal with:
Configurations and key bindings
All key combinations will be defined in the ~/.config/river/init configuration file.
Note that river does not currently support reloading the configuration. Instead, configurations can be changed on-the-fly by typing the corresponding riverctl command in a terminal, while permanent configurations can be changed via the init file.
River uses a dwm-inspired tags system for ordering and grouping windows to outputs. This system is superficially similar to the workspace system in most other WMs/Wayland compositors but are quite different.
Rather than assigning each window to a workspace, each window is assigned one or more tags as one of its properties. Every window and every output has 32 tags, which can either be on or off.
The following is heavily copy-pasted from :
To determine which windows should be currently displayed on an output, river loops through all windows and checks if any of its active tags match an active tag of the output. If there is a match, the window will be displayed. This system allows both windows and outputs to have multiple active tags simultaneously, which is what makes tags vastly more powerful than the workspaces of other compositors.
River allows both setting and toggling the tags of windows and outputs. Setting tags provides "on or off" information for each tag as a 32-bit unsigned integer to overwrite the previous value; toggling also provides river with the same 32-big unsigned integer, but instead of overwriting, river will toggle the matching tag of the window or output.
For example: Imagine you have a text editor on tag 1, a terminal where you are compiling the code on tag 2 and documentation on tag 3. While you are writing the codebase, you are on tag 1. If you want to reference the documentation, you can toggle tag 3 to have both the editor and the docs side-by-side. Now you want to compile, so you switch to tag 2; now only the terminal is on your screen. You compile but notice you have an error. You toggle tag 1 and now have your editor and your terminal with your compiler error side-by-side, allowing you to quickly find the bug. Compiling succeeds, so you toggle tag 2 and only your editor remains on the screen.
Besides the recommended terminal emulators and status bars as mentioned above, the authors also summarized various other recommended softwares here .
Please review the river wiki for FAQs and other issues .
Additional comments from editor(s)
- Make sure any autostart programs/scripts are defined at the beginning of the init file. Commands defined at the very end of the init file may not be run upon startup.
- bspwm — a lightweight, tiling, minimalist window manager that is written in C and represents its windows as leaves on a binary tree.
- dwm — a dynamic window manager for X11 from suckless.org.
- Sway — an open-source Wayland compositor that is designed to be compatible with the i3 window manager.
- Wayland — a simpler and modern replacement for X display server.