Umbriel: An Independent Wayland Compositor Built on wlroots

An Honest Account of What Umbriel Is and Why It Exists

Umbriel is a Wayland compositor built by a team that was unhappy with the compositors available to them. The README states this directly: "When people ask what Umbriel's selling point is, the honest answer is that there is no single killer feature. We were simply disappointed with the choices available to us, so we built the compositor we wanted to live in."

The project is developed alongside Noctalia, a desktop shell that provides application launching, status bars, and other desktop services specifically for Umbriel. The two are separate repositories and can be used independently. Umbriel's role is the compositor: it manages windows, workspaces, and rendering. Noctalia's role is the shell layer on top.

The README also carries a clear warning: Umbriel is young, usable now, but not stable. Configuration keys and keybinds may change between releases. That is an honest constraint for users evaluating it as a daily driver.

Layout System: Scrolling, Dwindle, and Master with Per-Workspace Selection

Umbriel provides three tiling layouts. Scrolling arranges windows in a horizontally scrollable row. Dwindle recursively subdivides the screen, splitting in alternating directions with each new window. Master splits the screen into a main area and a stack, with the focused window in the master position.

Layouts are selectable per workspace, not globally. Width presets, animated navigation, and mouse-driven resizing and reordering are supported within each layout. Windows can also be floating, pinned, or fullscreen with configurable placement and sizing.

Global named scratchpads let you hide window groups and summon them on any output. An animated overview provides a bird's-eye view of all windows. Directional focus using Vim-style keys (H/J/K/L) or arrows is built in, and submaps allow defining modal keybind layers. Activation policy is configurable, which controls whether focus follows the mouse or requires explicit keyboard input.

Visual Effects: Blur, Shadows, and Animated Transitions

Umbriel's visual effects layer is built on `umbrielfx`, its own hard fork of the SceneFX library. SceneFX extends wlroots' scene graph with visual effect support. The Umbriel fork (`umbrielfx/`) builds as part of the Umbriel tree rather than as a separate dependency.

Supported effects include per-window blur of the background, drop shadows, rounded corners, double borders (an inner and outer border), configurable opacity, and animated transitions for window position, size, and fade in/out. The blur, rounded corners, and shadow parameters are all configurable per window through window rules.

Kernel memory management is optional but recommended on glibc systems. The jemalloc allocator returns freed memory to the OS promptly and bounds heap fragmentation in long-running compositor sessions. Meson's `-Djemalloc=enabled` or `-Djemalloc=disabled` forces the choice at build time; the default (`auto`) uses jemalloc when its development package is installed.

Building Umbriel from Source

The build system is Meson with Ninja and a `justfile` for common tasks. The `umbrielfx/` scene graph and renderer build as part of the Umbriel tree rather than as a separate dependency, so there is no need to install it separately. The system build requires a C++23 compiler, Meson, Ninja, pkg-config, wayland-scanner, and development packages for wlroots 0.20.1 or newer, Wayland, xkbcommon, libinput, pixman, libdrm, EGL, GLES2, GBM, lcms2, Cairo, Pango, tomlplusplus, and nlohmann-json. The `libudev` package is needed for native DRM GPU exclusions.

A release build:

just release
just install

For Nix users, the flake builds the package directly:

nix build

The Nix development shell is the recommended environment for running tests:

nix develop
just test

The test suite uses a contained headless compositor harness. Each check gets its own compositor instance, so failures stay isolated. To run a specific check by name fragment:

just check 310

Failing checks preserve their runtime directory, which contains the compositor log, configuration, and per-client logs, with the path printed so a developer can inspect the failure state without re-running the check. Passing checks emit a concise completion message, condensed to a single dimmed line unless the `-v` flag is passed.

Running Umbriel and the TOML Configuration System

For installed sessions launched from a display manager, start through the provided launcher:

start-umbriel

The launcher loads the login environment, imports it into the systemd user manager, and starts the compositor as a user service on systemd or directly on other init systems.

For development testing, run the compositor with a specific application as the initial client:

just run debug kitty

Or start the debug binary directly:

./build-debug/umbriel -s kitty

From inside a running Wayland or X11 session, Umbriel opens a nested window rather than taking over the seat, which is useful for testing configuration changes without logging out. The default modifier key in nested mode is Alt; on DRM it is Super.

Configuration is TOML, live-reloaded at runtime. An `examples/config.toml` is included in the repository as a starting reference. The documentation warns that configuration keys are not stable and may change between releases. Diagnostics are shown when the config contains errors, and include files are supported for splitting large configurations.

X11 Support, Portal Integration, and Umbriel Versus Hyprland

X11 application support requires xwayland-satellite to be installed and on `PATH`. Xwayland-satellite is a third-party project that implements Xwayland support as a standalone process rather than inside the compositor. Screen capture and sharing for portal-aware applications (browser screen sharing, OBS, screenshot tools) are served by xdg-desktop-portal-umbriel, a separate repository that implements the Screencast and Screenshot portal interfaces.

Security-context-v1 is supported for sandbox engines, with per-application Wayland protocol grants. This allows restricting which protocols a sandboxed application can access, which matters for environments where applications are containerized.

Hyprland is the most commonly reached comparison point: it is also a C++-based dynamic Wayland compositor built on wlroots, with a focus on animations and visual effects. Hyprland has been in active development longer and has a larger user base, with extensive community documentation and plugins. Umbriel is newer, has fewer users, and explicitly avoids claiming it is the better choice. The README frames Umbriel as a project built for the developers' own use rather than as a response to Hyprland's design. Users who want a proven community-supported compositor should evaluate Hyprland first; users looking for something actively shaped by its creators and willing to handle configuration instability may find Umbriel worth watching.

Editorial conclusion

Umbriel suits Linux users who want a wlroots-based Wayland compositor with tiling layouts and visual effects and are willing to accept configuration churn as the project matures. It is a poor choice for anyone who needs a stable, production-ready configuration layer: the README explicitly notes that configuration keys, keybinds, and behavior may change between releases, and current defaults are described as opinions rather than stability promises. Before adopting it, verify that your GPU and Linux distribution can satisfy the wlroots 0.20.1 dependency and that xwayland-satellite is available if you need X11 application support. The last push was on 2026-09-27.

Frequently asked questions

Official sources

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