Umbriel: a wlroots Wayland compositor with scrolling layouts and its own SceneFX fork

What Umbriel solves, and for whom

Umbriel is a Wayland compositor for people who want a scrolling layout as a first-class option rather than an add-on. The README lists scrolling, dwindle and master layouts with per-workspace selection, width presets, animated navigation, and mouse-driven resizing and tiled reordering. That combination is the reason the project exists: the README answers its own "Why Umbriel?" section by saying there is no single killer feature, and that the authors were "simply disappointed with the choices available to us, so we built the compositor we wanted to live in." The stated plan is not to take over the big names.

The audience is narrower than a general desktop user. Umbriel runs independently, but it can be paired with Noctalia, a desktop shell from the same organisation, and the README describes Umbriel as "its compositor side." Portal screen capture and sharing come from a separate backend, xdg-desktop-portal-umbriel, which implements the Screencast and Screenshot interfaces. X11 applications work through xwayland-satellite, which the README says must be installed and on PATH. So the practical user is someone comfortable assembling a session from several pieces, not someone who expects one package to deliver a complete desktop.

The feature list is broad for a young project: global named scratchpads for hiding window groups and summoning them on any output, an animated overview, directional focus, submaps, layer shell, session locking, clipboard management, gamma control, and restricted Wayland connections through security-context-v1 with per-application protocol grants. Whether all of it is polished is a different question, and the README does not pretend otherwise.

wlroots plus a hard SceneFX fork: the architecture

Umbriel is built in C++23 on wlroots, and the scene graph and renderer live in umbrielfx, described as "its own hard fork" of SceneFX. The fork builds as part of the tree rather than as an external dependency, so renderer changes ship with the compositor instead of waiting on an upstream library. That is a real architectural decision with a real cost: fixes made in SceneFX upstream do not arrive automatically, and anyone packaging Umbriel packages the fork too.

The build targets wlroots 0.20, specifically 0.20.1 or newer. That is a hard floor, not a suggestion, and it is the kind of constraint that decides whether a distribution can build Umbriel at all. The dependency list is long: a C++23 compiler, Meson, Ninja, pkg-config, wayland-scanner, and development packages for Wayland, xkbcommon, libinput, pixman, libdrm, EGL, GLES2, GBM, lcms2, Cairo, Pango, tomlplusplus and nlohmann-json. Native [drm] GPU exclusions additionally require libudev.

Configuration is TOML, live-reloaded, with diagnostics and includes, plus local IPC and runtime inspection commands. Live reload matters more here than in a compositor with a frozen config schema, because the README warns that configuration keys, keybinds and behavior may change between releases. A reload cycle shortens the feedback loop when a key moves.

The project also runs nested inside an existing Wayland or X11 desktop for development, or directly on DRM for daily use. In nested mode the modifier is Alt; from a TTY it takes over the seat and the modifier is Super.

Building and running Umbriel from a TTY

The README documents a system build through Just recipes. After installing the dependencies listed above, the two commands are release and install. The README does not state a version number for just itself, so treat the recipe names as the interface.

just release
just install

Binaries land in build-debug/umbriel and build-release/umbriel, so a debug build is available without reconfiguring. jemalloc is optional but recommended on glibc: the README says it returns freed memory to the OS promptly and bounds heap fragmentation in long-running sessions. Meson's -Djemalloc=enabled or -Djemalloc=disabled forces the choice, and the default auto uses it when the development package is installed.

Nix users get a different path. The flake builds the package directly, and the resulting binary is at result/bin/umbriel.

nix build

For development, nix develop enters the project shell, and the same Just recipes apply. Starting an installed session from a TTY is one command:

start-umbriel

From an existing Wayland or X11 session, Umbriel opens a nested window instead of taking over the seat. The README gives two ways to launch a nested session with a client, a Just recipe and the binary directly:

just run debug kitty
./build-debug/umbriel -s kitty

Inside the session, mod+Escape quits after a confirmation prompt, and mod+F1 appears in the shortcut table the README begins but does not finish in the text available here. For a first real use, the nested window is the safer entry point: it leaves your current session intact while you learn the keybinds.

Configuration churn is the main risk, and the README says so

The README carries an explicit warning: Umbriel is young and actively evolving, configuration keys, keybinds and behavior may change between releases, rough edges remain, and "current defaults are opinions, not stability promises." That is unusually direct, and it should shape how you evaluate the project. A compositor whose config schema moves between releases imposes a recurring migration cost on anyone who maintains a hand-written config, and the README does not document a migration tool or a deprecation window for renamed keys.

A second limitation is environmental. Xwayland support is not built in. It comes from xwayland-satellite, which must be installed and on PATH. If you run an X11-only application and xwayland-satellite is missing, the README gives no fallback. Portal-based screen capture has the same shape: browser screen sharing, OBS, and portal-aware screenshot tools are served by xdg-desktop-portal-umbriel, a separate repository. Umbriel on its own does not provide them.

There is also a packaging gap. The repository has no published GitHub releases, so there is no tagged artifact to pin and no changelog to read before upgrading. The README points distribution maintainers at PACKAGING.md for the installed layout, dependency notes and config fallback, which suggests packaging is a supported activity, but it is not the same as a release you can hold.

Finally, the wlroots 0.20.1 floor is a hard gate. On a distribution that ships an older wlroots, the build stops there, and the README offers no compatibility path.

How Umbriel differs from Hyprland and from a standalone wlroots compositor

The closest comparison is Hyprland, which is also a C++ Wayland compositor with tiling layouts, animations, blur and rounded corners. The difference in approach is the rendering layer. Umbriel carries umbrielfx, a hard fork of SceneFX, inside its own tree, so its scene graph and renderer are versioned with the compositor. Hyprland's rendering stack is its own as well, but the point stands: neither is a thin wrapper over stock wlroots rendering, and choosing between them is choosing between two separate rendering implementations rather than two configurations of one.

A second difference is the layout model. Umbriel treats scrolling as a peer of dwindle and master, with per-workspace selection, width presets and mouse-driven tiled reordering. Compositors that offer scrolling as a plugin or a patch make it a second-class citizen; here it is in the core feature list.

The third axis is the shell. Umbriel is designed to pair with Noctalia, which the README calls "a first-class desktop shell experience for Umbriel." If you already run Noctalia, Umbriel is the compositor half of that stack. If you run a different shell, the pairing is not documented.

Against a plain wlroots compositor assembled from examples, Umbriel is the opposite trade: you get layouts, blur, shadows, scratchpads and an overview out of the box, and you accept a much larger dependency surface and a moving config schema.

Testing, maintenance and licence

The last push to the default branch was on 2026-09-16, and the repository is not archived, so this is a project under current work rather than a dormant one. The repository has no published GitHub releases, which means the main branch is effectively the artifact.

The test story is more developed than the release story. Unit tests and a contained headless compositor harness are two commands inside the Nix development shell, one for the unit and umbrielfx suites through Meson, one for every harness check.

nix develop
just test
just check

Each check gets its own contained headless compositor, so a failure stays local and checks run in any order. just check takes name fragments, just check-names lists them, and a failing check keeps its runtime directory (compositor log, config, per-client logs) and prints the path. That is a useful design for a compositor, where a single global session would otherwise couple unrelated checks. The justfile also defines an asan mode, and notes that leak detection is off there because Mesa leaks its EGL setup on every renderer teardown, which would bury a real finding. That comment is worth reading before you interpret an asan run as clean.

Upgrade cost follows from the missing releases. Without tags, an upgrade means moving to a new commit and re-reading the README and docs for key changes. Budget time for that on every update, not just major ones.

The licence is MIT. That is permissive and imposes no copyleft obligation on your own code, but it also means no warranty, and the README's stability caveats are the practical expression of that. Nothing here is legal advice; read LICENSE and PACKAGING.md if you plan to redistribute.

Editorial conclusion

Adopt Umbriel if you want a wlroots compositor with scrolling, dwindle and master layouts, per-output workspaces and a live-reloaded TOML config, and you accept that keybinds and keys can move between releases. Do not adopt it if you need a stable configuration contract or a packaged release to pin, because the repository has no published GitHub releases and the README states defaults are opinions rather than stability promises. Before installing, confirm that wlroots 0.20.1 or newer is available on your distribution, that xwayland-satellite is on PATH, and that you can build with Meson, Ninja and a C++23 compiler.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. noctalia-dev/umbriel on GitHub
4. Project website
5. README