What Is rivertile? The Beginner's Guide to River's Default Layout Generator (External Layouts, Explained)

CodexFuse Team · 2026-11-04T15:17:12.492Z · 10 min read min read

What Is rivertile? The Beginner's Guide to River's Default Layout Generator (External Layouts, Explained)

If you have been reading a river config file and wondering what is rivertile, exactly — this is rivertile explained for beginners. rivertile is the small, bundled layout generator that tiles your windows on the river Wayland compositor: river itself handles rendering and input, and rivertile decides where every window goes. It is not the compositor, not a window manager, and not a full desktop environment — it is one modest program with one job, launched from your river config with two commands. This guide covers the external-layout concept, how to enable rivertile, its startup options and live-tweak commands, what happens when you skip it, and the one thing every new user must know first: since river 0.4, rivertile only works on the river-classic line.

river is driven almost entirely from the keyboard, so before you start remapping keys, confirm your modifier keys actually register with our keyboard tester. A dead Super key will make any tiling setup feel broken.

What Is rivertile, Exactly?

rivertile is a layout generator for river: the official man page defines it as "rivertile - tiled layout generator for river" and explains that "it provides a simple tiled layout with split main/secondary stacks." In practice, that means one big window on the left (the "main" area, usually your terminal or editor) and the rest of your windows stacked in a narrower secondary area on the right. river sends rivertile the list of open windows and the screen dimensions; rivertile sends back the rectangle each window should occupy; river draws them there.

The project's own README for the classic line puts it plainly: "A basic layout generator, `rivertile`, is provided but users are encouraged to use community-developed layout generators or write their own." Think of rivertile as training wheels and a reference implementation at the same time: it works out of the box, and it demonstrates exactly how little code a layout generator needs to be.

Why Does river Ship Its Tiling to a Separate Program?

Because river's core design decision is that the compositor should never decide where windows go. The classic river wiki states it as a hard fact: "River does not have any built-in layouts and depends entirely on external programs to dynamically arrange views." Tiling policy lives in a separate, replaceable process that speaks a custom river-layout protocol to the compositor.

The idea comes straight from dwm's lineage. river's author wrote that "River's window management is based on a linear stack of windows much like dwm. These windows are arranged by a separate program called a layout generator," and that "users are encouraged to write and share their own layout generators, they are simply Wayland clients which implement a custom river-layout-v3 protocol." That last detail is why river configs read like scripts rather than setting files: you are wiring together independent programs, not configuring one monolith. Contrast this with a compositor that tiles internally — the stacking compositor labwc, for instance, handles window placement itself — and you can feel how different the river philosophy is.

rivertile Tutorial: How Do You Turn It On?

rivertile is a daemon, not a one-shot command: it must be running before you ask river to use it, and it stays running for your whole session. The official river-classic wiki gives this exact two-line recipe for your river init script:

1. Start rivertile in the background so it is available to the compositor: riverctl spawn rivertile. The spawn command tells river to launch the program, keeping it tied to your session.
2. Assign rivertile as the layout generator for the currently focused output: riverctl output-layout rivertile. You can also set a default for every output instead of doing it per-monitor.
3. Reload or restart river (or run both lines interactively with riverctl) and open a few windows: they should tile immediately with no further configuration.
4. Verify it is active: if windows tile, rivertile is handling your output; if they float, you skipped a step — see the troubleshooting section below.

One naming gotcha the wiki flags explicitly: "The name of the layout is not guaranteed to be equal to the filename of the executable." For rivertile the names do match, which is convenient — but once you try community generators, remember that the layout name you pass to output-layout is whatever the generator registers, not necessarily its file name.

These commands assume you are running river on real Linux hardware. If you are testing in a throwaway environment, a VPS hosting instance with a Wayland-capable stack is a safe place to experiment before you touch your daily driver.

What Are rivertile's Startup Options?

rivertile's initial state is set with command-line flags at launch. All of them have sane defaults, so rivertile with no flags gives you a perfectly usable tiled layout, but knowing the flags lets you shape the desktop before it opens. Every flag below is taken verbatim from the rivertile(1) man page:

The man page's own example shows how flags combine in one launch line: rivertile -outer-padding 4 -main-location top puts a tighter screen-edge gap with the main area along the top. That is the whole configuration surface of the program — there is no config file, no theme engine, and exactly one layout: a simple tiled arrangement with split main and secondary stacks. Claims that stock rivertile has fullscreen, grid, or monocle "modes" are wrong; those belong to forks like rivercarro.

How Do You Change rivertile's Layout Without Restarting It?

You do not need to relaunch rivertile to adjust the tiling: it accepts layout commands while it runs through riverctl. The man page documents three runtime commands, sent with riverctl send-layout-cmd rivertile "<command>":

Typical live tweaks look like this: riverctl send-layout-cmd rivertile "main-ratio +0.1" widens the main area by a tenth, and riverctl send-layout-cmd rivertile "main-count 3" promotes two more windows into the main stack. Bind these to keys in your river config and you have a fully keyboard-driven layout control surface — which is the whole point of running river in the first place. Since rivertile is the default, these commands also make excellent first experiments before you write a layout generator of your own.

What Happens If You Run river Without Any Layout Generator?

river degrades gracefully: it falls back to floating window management. The wiki is explicit that "if no layout generator is active for the current output, river will fall back to floating window management," and adds that "river is perfectly usable in this floating mode, thanks to the move, resize and snap commands." So if your windows suddenly float instead of tiling, the cause is almost always one of two things: rivertile is not running (it died, or you never spawned it), or you never assigned it with output-layout for that output.

This is the most common "bug" new river users report, and it is by design. The compositor is doing exactly what it was told: with no external program claiming the layout namespace, it manages windows the only way it can — floating, like a traditional desktop. Two lines in your init script and the mystery is solved permanently.

Does rivertile Work With River 0.5? The Split Explained

No — and this is the single most important thing to know before you install. In river 0.4 the project split its architecture: the compositor now handles only rendering and input, and window management moved into a separate window-manager process speaking the stable river-window-management-v1 protocol. The Gentoo wiki states the consequence bluntly: "As of version 0.4, river requires an external window manager ... riverctl and rivertile are no longer supported." As of November 4, 2026, the newest river release is 0.5.0 (published October 10, 2026), and rivertile does not run on it.

The dynamic-tiling line did not die — it became river-classic, "a maintained fork of river 0.3 intended for users that are happy with how river 0.3 works," whose newest release is 0.3.17 (April 30, 2026). If you want rivertile, you want river-classic: Arch ships it as extra/river-classic 0.3.17-2, Alpine installs it with apk add river-classic river-classic-doc, and openSUSE even packages rivertile as its own river-rivertile subpackage. Fedora users should note there is no official Fedora package — only an old review request and an unofficial COPR. The project's own new README even redirects: "If you are looking for the old dynamic tiling version of river, see river-classic."

This split mirrors what the broader Wayland world is doing: modular desktops where each layer does one thing well. It is the same instinct behind the tiling-first distro Omarchy shipping its launcher as a separate component rather than baking it in — pick the layer you want, swap the rest.

rivertile vs Community Layout Generators

rivertile is the starting point, not the ceiling. river's author explicitly encourages users to "write and share their own layout generators," and the ecosystem has produced several: Alpine's repositories carry rivercarro (a fork of the rivertile layout with extras like per-tag settings and monocle) and river-luatile (lets you write layouts in Lua instead of Zig or C). The river-classic README points to example layout generators in C and Python to lower the entry barrier further.

The practical decision is simple. Stay on rivertile if you like one predictable tiled layout and keyboard tweaks are enough. Move on when you catch yourself wanting something rivertile cannot do — a grid, a fullscreen workflow, per-tag layouts, or a layout that arranges windows by application. And if you want a launcher to pair with your tiled desktop, the Walker guide shows how a purpose-built launcher slots into the same ecosystem: compositor, layout generator, and launcher each doing their own job.

Sources

All facts verified live on November 4, 2026. river-classic wiki FAQ ("My windows are not tiled!"), codeberg.org/river/wiki-classic; Isaac Freund, "Introducing River, a Dynamic Tiling Wayland Compositor," isaacfreund.com; river-classic README, codeberg.org/river/river-classic; river README, github.com/riverwm/river (mirror); rivertile(1) man page, man.archlinux.org; Bobby Borisov, "River 0.4 Wayland Compositor Debuts Pluggable Window Managers," linuxiac.com; River wiki, wiki.gentoo.org; "river - dynamic tiling Wayland compositor," linuxlinks.com; "River Project Swims Against the Wayland Tide with Modular Window Management," techedubyte.com; River wiki, wiki.alpinelinux.org; Arch Linux package search, archlinux.org; FreshPorts package message, x11-wm/river.

Frequently Asked Questions

Is rivertile the same thing as river?

No. river is the Wayland compositor (and, on the classic line, the tiling window manager); rivertile is just the small bundled program that computes window rectangles for river. You can run river without rivertile — windows simply float — but rivertile cannot run without river, because it only speaks river's layout protocol.

Does rivertile work with the newest river 0.5?

No. Since river 0.4, the new river line defers all window management to a separate window-manager process and no longer supports layout generators or rivertile. To use rivertile you install river-classic, the maintained fork of the 0.3 dynamic-tiling line, currently at 0.3.17. This split is documented in the project's own README, the Gentoo wiki, and the FreshPorts package message.

How do I change rivertile's layout without restarting it?

Send it layout commands through riverctl while it runs: riverctl send-layout-cmd rivertile "main-ratio +0.1" to widen the main area, or riverctl send-layout-cmd rivertile "main-count 3" to put three windows in the main stack. Ratios are clamped between 0.1 and 0.9, and the main count never drops below 1. Startup flags like -main-location top only apply when you first launch it.

Can I use a different layout generator instead of rivertile?

Yes — that is the entire point of the external-layout design. Community generators include rivercarro (a rivertile fork with per-tag settings and monocle) and river-luatile (write layouts in Lua), and the river-classic README links example generators in C and Python. Spawn your chosen generator the same way (riverctl spawn) and point riverctl output-layout at its registered layout name.

Why are my windows floating instead of tiled?

Almost always because no layout generator is active on that output: either rivertile is not running (you never spawned it, or it died) or you never assigned it with riverctl output-layout rivertile. Remember that layout generators are constantly running daemons, not one-shot programs, and that the assignment is per output — check both lines in your init script.