Skip to content

Home

Jump to bottom
Leon Henrik Plickat edited this page Sep 3, 2022 · 37 revisions

Welcome to the river wiki!

Here you will find information, guides, tips and tricks that do not fit into the main documentation.

Feel free to contribute!

FAQ

How do I reload the configuration file?

You don't. The default river init is a shell script executing riverctl a bunch of times to configure river. If you want to change a setting, just run the corresponding riverctl command again with the updated value.

Wait, the configuration is a shell script?

The default one is a shell script, yes. However, since river just tries to run an executable file called init on startup (for possible locations of the file see the man page), it can be anything. You could configure river using a python script or a compiled C program if you wanted to, just make sure the file is executable and in the right place.

How can I configure outputs?

River implements the wlr-output-management-unstable-v1 protocol extension to allow external programs to configure its output. To keep river simple, this is the only way to configure outputs. See the Recommended Software section of this wiki to find out which output configuration programs we recommend.

My windows are not tiled!

You probably forgot to either run a layout generator or to configure the layout namespace of the output. River does not have any built-in layouts and depends entirely on external programs to dynamically arrange views. If no layout generator is active for the current output, river will fall back to floating window management. River is perfectly usable in this floating mode, thanks to the move, resize and snap commands.

To use a layout generator, make sure it is running (they are constantly running daemons, not one-shot programs) and then enable it in river (either per output or as a global default).

As an example, this following snippet will start rivertile, rivers default and bundled layout generator, in the background and then tells river to use it on the currently focused output.

riverctl spawn rivertile
riverctl output-layout rivertile

Behold: The name of the layout is not guaranteed to be equal to the filename of the executable.

How do I set a wallpaper?

River itself does not support displaying image. Instead you will have to use an external program, like for example swaybg. You can imagine these wallpaper programs to be like image viewers that just run in the background (using the layer shell).

River does not appear in my display managers session selector!

River ships with a session file, but by default does not install it because display managers are not officially supported.

If you wish to install it, copy river.desktop (from the river/contrib directory) to /usr/share/wayland-sessions/. However, note that not every display manager supports Wayland sessions.

River won't run on my Raspberry Pi!

Try adding dtoverlay=vc4-kms-v3d in /boot/config.txt.

How do I disable GTK decorations (e.g. title bar)?

River by default disables CSD (Client-side decoration) but GTK use an obsolete protocol. See #24 for more information.

In the meantime, for Firefox you can do this: Right click on toolbar and click on "Customize Toolbar...". In the bottom, uncheck "Title Bar".

It is also possible to remove GTK window buttons with gsettings set org.gnome.desktop.wm.preferences button-layout ""

How do I use multiple keyboard layouts?

As you already know from river(1), the keyboard layout is configured by setting the XKB_DEFAULT_LAYOUT env var before starting river (setting it in your init will not work). If you want to use multiple keyboard layouts, you can write them all into the env var, comma separated:

export XKB_DEFAULT_LAYOU="de,en"

To switch between all configured layouts, you can set up a keybind via an XKB option. For example like this:

export XKB_DEFAULT_OPTIONS="grp:ctrl_shift_toggle"

Note that you can unfortunately not use any arbitrary key combination for this bind, only a select list of predefined options. See xkeyboard-config(7) for all available options.

What are the minimum hardware requirements for running river?

River runs well on a ThinkPad X200 from 2008. Any newer hardware should be perfectly fine, as long as you don't use proprietary graphics drivers.

Where can I get more help?

Probably the best place to get help is the #river channel on irc.libera.chat. Before actually asking, you may be able to save yourself some time by searching the archives to see if your question has already been answered. Use the "Enter keywords" box and click "Search".

Clone this wiki locally