Umbriel is a Wayland compositor designed for daily use, with scrolling and dwindle layouts, per-output workspaces, window rules, blur, shadows, and fluid animations.
It runs independently and can be paired with Noctalia, which provides a first-class desktop shell experience for Umbriel. Umbriel is built in C++23 on wlroots and SceneFX, with Xwayland support provided by xwayland-satellite and portal screen capture and sharing by xdg-desktop-portal-umbriel, an xdg-desktop-portal backend for Umbriel.
Important
Umbriel is young and actively evolving. It is usable today, but configuration keys, keybinds, and behavior may change between releases, and rough edges remain. Current defaults are opinions, not stability promises.
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 plan is not to conquer the world or take over the big names; it is to feel at home with something we have a say in, with less friction. That is exactly how Noctalia came to life, and Umbriel is its compositor side.
To understand the values and philosophy guiding the project, read our ethos.
- Scrolling and dwindle layouts with per-workspace selection, width presets, animated navigation, and mouse-driven resizing and tiled reordering
- Independent workspaces per output, with hotplug support and configurable modes, positions, scales, and transforms
- Floating, pinned, and fullscreen windows with configurable placement, focus, sizing, opacity, and visual effects
- Per-output scratchpads for temporarily hiding windows, with toggle, move, restore, and focus-next actions
- An animated overview, directional focus, configurable keybinds, submaps, and activation policy
- Blur, shadows, rounded corners, double borders, opacity, and animated position, size, and fade transitions
- Keyboard, pointer, touch, touchpad gestures, XKB configuration, and text-input-v3/input-method-v2 input method support
- Layer shell, session locking, clipboard management, screen capture, output control, and gamma control
- X11 application support through xwayland-satellite
- Live-reloaded TOML configuration with diagnostics and includes, plus local IPC and runtime inspection commands
- Runs as a nested Wayland compositor inside an existing Wayland or X11 desktop for development, or directly on DRM for daily use
Distribution maintainers should also read PACKAGING.md for the installed layout, dependency notes, SceneFX requirements, and config fallback.
After cloning, initialize the patched SceneFX fork tracked in subprojects/scenefx:
git submodule update --initInstall a C++23 compiler, Meson, Ninja, pkg-config, wayland-scanner, and development packages for wlroots 0.20, Wayland, xkbcommon, libinput, pixman, libdrm, Cairo, Pango, tomlplusplus, and nlohmann-json. Then build Umbriel:
just release
just installjemalloc is optional but recommended on glibc: 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; the
default (auto) uses it when the development package is installed and skips it otherwise (non-glibc libc builds
always skip it).
The binaries are written to build-debug/umbriel and build-release/umbriel. Meson uses a system scenefx-0.5
only when its headers provide the required APIs; otherwise it builds the initialized submodule.
Build the package directly:
nix buildThe resulting binary is available at result/bin/umbriel. For development, enter the project shell and use the same
Just recipes as a system build:
nix develop
just debugThe development shell includes the clients and command-line tools used by the test suite. Run unit tests and the contained headless compositor harness with:
nix develop
just test
just verifyWhile iterating, just check runs single harness checks by name fragment on the
default build, and just checks lists the available names:
just check 120 # one check
just check 118 120 # several
just check 120 -v # keep the full output of passing checksA run reports one line per check with its duration; passing checks are
summarized to a single dimmed line while failing ones print their whole output.
A failing run keeps its runtime directory (compositor log, per-client logs) and
prints the path. just verify <mode> [fragment ...] selects another build.
Installed display-manager sessions start through start-umbriel. On systemd,
it runs the compositor as a user service so applications inherit
environment.d; other init systems fall back to the compositor binary.
Start an installed native session from a TTY with:
start-umbrielFrom an existing Wayland or X11 session, Umbriel opens a nested window (mod = Alt). From a TTY it takes over the seat (mod = Super).
Apps that capture the screen through xdg-desktop-portal (browser screen sharing, OBS, portal-aware screenshot tools) are served by xdg-desktop-portal-umbriel, which implements the Screencast and Screenshot interfaces for Umbriel.
just run debug kittyOr run the binary directly:
./build-debug/umbriel -s kittyInside the session:
| Shortcut | Action |
|---|---|
| mod+Escape | Quit (asks for confirmation) |
| mod+F1 | Cycle window focus |
| mod+H/J/K/L or arrows | Focus adjacent window |
| mod+Shift+H/J/K/L or arrows | Move focused window |
| mod+comma / mod+period | Consume left / expel right |
| mod+R / mod+F | Cycle width / toggle fullscreen |
| mod+T | Toggle floating for the focused window |
| mod+P | Toggle pin for the focused window |
| mod+O | Toggle the overview |
| mod+1..9 | Switch workspace on focused monitor |
| mod+Shift+1..9 | Move focused window to workspace and follow |
kitty is an optional startup command. Replace it with another command, or omit it by running just run debug
or ./build-debug/umbriel. There is no default spawn keybind, so add one under [keybinds] (see
examples/config.toml) to open more terminals from inside the session, e.g. "Mod+Return" = "spawn:kitty".
Stop with mod+Escape or Ctrl+C from the parent terminal.
Umbriel first checks $XDG_CONFIG_HOME/umbriel/config.toml, then $XDG_CONFIG_DIRS, and finally its packaged
share/umbriel/config.toml. Pass -c path/to/config.toml to use another file. Config files can include files with
[include] files = ["theme.toml", "keybinds.toml"]; later files and the main file override earlier values.
See examples/config.toml for the packaged starting configuration and
docs/user/ for the full reference:
- Configuration: general, appearance, layout, input
- Keybinds: chords, submaps, Noctalia integration
- Scratchpads: setup, workflow, and multi-output behavior
- Window and Layer Rules: matching, effects, blur
- Outputs: monitors, workspaces, workspace layout overrides
- Maintainer design notes: reloads, workspaces, and overview rendering
Declarative configuration uses Nix attrsets serialized to TOML with pkgs.formats.toml.
# flake inputs
umbriel.url = "git+https://github.com/noctalia-dev/umbriel";
xdg-desktop-portal-umbriel.url = "github:noctalia-dev/xdg-desktop-portal-umbriel";
# NixOS
imports = [ inputs.umbriel.nixosModules.default ];
programs.umbriel = {
enable = true;
portalPackage = inputs.xdg-desktop-portal-umbriel.packages.${pkgs.stdenv.hostPlatform.system}.default;
};
# home-manager
imports = [ inputs.umbriel.homeModules.default ];
programs.umbriel = {
enable = true;
settings = {
general.autostart = [ "noctalia" ];
layout.gap = 5;
input.keyboard.layout = "de";
keybinds = {
"Mod+Return" = "spawn:kitty";
"Mod+Q" = "window-close";
"Mod" = "spawn:noctalia msg panel-toggle launcher";
};
};
};The portal lives in a separate repository and can
be used via a separate flake input. Setting portalPackage will configure the xdg.portal backend and install
the portal configuration, which is required for screencasting.
When settings is omitted, the Home Manager and hjem modules leave the user path untouched so Umbriel loads its
packaged configuration. Home Manager also accepts a raw TOML string or a path. The hjem module is exported as
inputs.umbriel.hjemModules.default.
See CONTRIBUTING.md for code style, naming conventions, the dependency stack, and debugging helpers. Umbriel shares its conventions with noctalia. For general help and design discussion, join the community on Discord.
MIT License. See LICENSE for details.