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, just open a PR to the codeberg repository.

If you are using river 0.3.x aka river-classic see the wiki for river-classic instead.

Pages

• List of Window managers
• Useful Software

FAQ

How can I configure outputs?

River implements the wlr-output-management-unstable-v1 protocol to allow external programs to configure outputs. This is the only way to configure outputs. See the Useful Software page for a list of tools leveraging this protocol.

Why doesn't screensharing work?

River supports the wlr-screencopy-v1 protocol but some clients only support xdg-desktop-portal + pipewire for screensharing.

The xdg-desktop-portal-wlr project provides an implementation of the required xdg-desktop-portal interfaces and communicates with river through the wlr-screencopy-v1 protocol.

Install and configure xdg-desktop-portal-wlr to make screensharing work in Firefox, Chromium, OBS, and more.

See the xdg-desktop-portal-wlr troubleshooting checklist if you have issues.

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/local/share/wayland-sessions/. However, note that not every display manager supports Wayland sessions.

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

GTK unfortunately does not support the standard xdg-decoration protocol but rather the obsolete KDE server-decoration protocol. See #24 for more information.

Workaround for Firefox

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 ""

Woraround for Emacs

(setq default-frame-alist '((undecorated . t)))

Global workaround by modifying GTKs source

One may also apply this 1 line patch to gtk3:

diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 8df1c8e861..d102017942 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -6121,8 +6121,7 @@ gtk_window_should_use_csd (GtkWindow *window)
 #ifdef GDK_WINDOWING_WAYLAND
   if (GDK_IS_WAYLAND_DISPLAY (gtk_widget_get_display (GTK_WIDGET (window))))
     {
-      GdkDisplay *gdk_display = gtk_widget_get_display (GTK_WIDGET (window));
-      return !gdk_wayland_display_prefers_ssd (gdk_display);
+      return FALSE;
     }
 #endif

Global workaround using GTK CSS

GTK decorations can also be customized by creating or modifying the ~/.config/gtk-3.0/gtk.css and ~/.config/gtk-4.0/gtk.css files to hide the title bar:

/* No (default) title bar on wayland */
headerbar.default-decoration {
  /* You may need to tweak these values depending on your GTK theme */
  margin-bottom: 50px;
  margin-top: -100px;
}

/* rm -rf window shadows */
window.csd,             /* gtk4? */
window.csd decoration { /* gtk3 */
  box-shadow: none;
}

This approach will retain the functionality of windows with customized title bars, eg. file picker dialogs with buttons in the title bar. If you want to remove those title bars as well without breaking them, change this option in ~/.config/gtk-3.0/settings.ini and ~/.config/gtk-4.0/settings.ini to move those buttons to the bottom of the window:

[Settings]
gtk-dialogs-use-header=false

How to autostart river at login from tty?

Add these lines to your shell's .profile (.bash_profile for Bash, .zprofile for ZSH):

if [ -z "$WAYLAND_DISPLAY" ] && [ $(tty) = "/dev/tty1" ]; then
  exec river
fi

It's going to autostart river, if you are on tty1.

If you want to redirect logs to file, add > ~/.river.log 2>&1 after exec river.

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?

The best place to get realtime help is the #river IRC channel on 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".