Skip to content

Configuration

The packaged starting configuration is examples/config.toml. Copy it before making local changes:

Terminal window
mkdir -p ~/.config/umbriel
cp /usr/share/umbriel/config.toml ~/.config/umbriel/config.toml

A manual installation under /usr/local places it at /usr/local/share/umbriel/config.toml. Nix users should prefer programs.umbriel.settings in Home Manager or hjem.

Umbriel watches the active configuration and applies valid changes when you save. Most options reload immediately; reference tables identify options that require a restart. If a reload fails, Umbriel keeps the last working configuration and tries again on the next save.

Without -c, Umbriel checks these locations in order:

  1. $XDG_CONFIG_HOME/umbriel/config.toml
  2. Each $XDG_CONFIG_DIRS/umbriel/config.toml
  3. The packaged share/umbriel/config.toml

Use umbriel -c <path> to select one exact file. Umbriel never creates or modifies a user configuration automatically.

Configuration warnings and errors appear in a panel on the primary output. Errors keep the previous working configuration active. A warning-only panel closes after ten seconds; an error remains until the next successful reload.

Every configuration diagnostic is also written to umbriel.log with the same file, line, and column, so a session started without a terminal still records what the panel showed after it closes. Diagnostics are logged where a load’s outcome is decided: for the configuration about to be applied, and for a reload that was rejected. A refused umbriel config set or config replace writes nothing because its load is rolled back.

Check a file without starting the compositor:

Terminal window
umbriel config validate

The command prints every diagnostic with its file, line, and column, and exits nonzero when it finds a problem.

For editors and scripts, --json (or -j) prints one JSON object with valid, the configuration path, and a diagnostics array. Each diagnostic has severity ("error" or "warning"), message, file, line, and column; the location fields are null when unknown. The exit status is the same as without the flag.

Terminal window
umbriel config validate --json | jq -r '.diagnostics[] | "\(.severity): \(.message)"'

List every configuration key the installed binary accepts:

Terminal window
umbriel config schema
umbriel config schema --json

Without --json it prints how many options each section has. With --json it prints each key’s path, type, range, accepted values, format, and built-in default, plus the binary’s version and revision (null for a build outside git). name[] marks the entries of an array of tables, such as window_rule[].match.app_id, and <name> a name you choose, such as output.<name>.scale.

Split a configuration into smaller files with required or optional includes:

[include]
files = [
"appearance.toml",
"keybinds.toml",
]
[include.optional]
files = [
"~/.config/umbriel/noctalia.toml",
]

Paths are relative to the file containing the include. ~, $VAR, and ${VAR} are expanded. Missing optional files are ignored and watched, so creating one later reloads the configuration.

Included files are applied in list order. The including file is applied last:

  • Tables merge by key.
  • Rule lists such as [[window_rule]] and [[workspace]] collect entries.
  • Plain arrays and scalar values are replaced by the last file that sets them.
  • Setting a rule list to [] discards entries collected earlier.

Every file must contain valid TOML. Duplicate device or workspace selectors, and an effect preset defined in two files, are errors even when they come from different files. At startup, any configuration error makes Umbriel use the default configuration and show an error banner; a reload keeps the previous configuration.

If any included file defines [drm], also declare [drm] in the main file. This prevents an incomplete GPU exclusion policy from loading when an include is unavailable.

Change a value in the running session without editing the file, for example to turn a touchpad off for a while:

Terminal window
umbriel config set input.touchpad.enabled false
umbriel config get input.touchpad.enabled
umbriel config unset input.touchpad.enabled

config set <key> <value> takes a dotted key, as in umbriel config schema --json, and a TOML value: quote strings for the shell and for TOML, as in umbriel config set appearance.title_bar.font "'Inter 10'". Quote a key segment that holds a dot or other punctuation, as in 'output."HDMI-A-1".scale'. A table or array value replaces what the file holds at that key, so a rule list such as [[window_rule]] cannot be extended one entry at a time, and include cannot be set.

Overrides live in memory only. They are never written to a file and last until the compositor exits. They stay on top of the file through reloads and config-replace, so saving the file never undoes them. A value that produces any new error or warning is refused and changes nothing; the reply lists why. Relative shader and profile paths need a file to resolve against, so give overrides absolute paths.

config get <key> prints the active value: the override, else the file’s value, else the built-in default. Strings print bare and other values as JSON. With --json the reply is {"value": ..., "override": true|false}. A table key prints the whole table.

config unset <key> drops one override so the file or default applies again, and config unset --all drops every override.

[general]
autostart = ["noctalia", "kitty"]
mod_key = "Super"
xwayland = true
xwayland_native_resolution = false
xwayland_xsettings = true
xwayland_primary_output = ""
nvidia_sync_workaround = true
show_cheatsheet = true
focus_on_activate = false
attach_modal_dialogs = true
honor_restored_maximize = false
KeyTypeDefaultDescription
autostartstring array[]Commands started once with the session. Changes require a restart.
mod_keystringSuper, or Alt when nestedModifier represented by Mod in keybinds.
xwaylandbooltrueStart Xwayland lazily for X11 applications. Changes require a restart.
xwayland_native_resolutionboolfalseShow outputs to X11 applications at their physical resolution, so they render sharp on scaled outputs. Changes require a restart.
xwayland_xsettingsbooltrueAnnounce the interface scale and cursor theme to X11 applications through XSETTINGS. Turn it off to run your own XSETTINGS manager, such as xsettingsd. Changes require a restart.
xwayland_primary_outputstring""Connector or monitor identity to publish as the X11 primary monitor. Applies on reload. Empty leaves primary selection unmanaged.
nvidia_sync_workaroundbooltrueWait for GPU completion on composed NVIDIA outputs without explicit synchronization. Applies on reload. See NVIDIA synchronization.
show_cheatsheetbooltrueShow the keybind cheatsheet when Umbriel starts.
focus_on_activateboolfalseLet application activation requests focus and reveal their target.
attach_modal_dialogsbooltrueAttach a modal dialog to its parent, so it follows the parent and holds its input. See Dialogs.
honor_restored_maximizeboolfalseHonor maximize requests an application makes while its window opens, until it acknowledges its opening layout.

Xwayland must be installed and available on PATH when X11 support is enabled. It starts when the first X11 application connects.

X11 bounding shapes clip windows to their visible regions, including holes and separate rectangles. Shape changes apply while the window is open and are preserved in overview previews, window captures, and close animations. Input shapes remain independent, so a click-through overlay can keep drawing its visible widgets.

X11 applications have no per-output scale. By default they see every output at its logical size, and Umbriel upscales their windows on outputs with a scale above 1, which looks soft. With xwayland_native_resolution = true they see each output at its physical size instead: a 3840x2160 output at scale 1.25 appears to them as 3840x2160 rather than 3072x1728. Their windows render at one pixel per screen pixel and stay sharp, but X11 applications that do not scale their own interface look smaller on scaled outputs. Games benefit most.

With xwayland_xsettings = true, Umbriel tells X11 applications that read XSETTINGS, such as GTK, Chromium, Electron, and Steam, the scale to draw their interface at: the largest output scale with xwayland_native_resolution = true, and 1 without it. It also announces [input.cursor] theme and size, the size scaled the same way. At native resolution X11 has one scale for every output, so on outputs with a smaller scale these applications look larger than native ones.

Some X11 games and Wine applications enumerate resolutions from the X11 primary monitor, independently of where Umbriel places their windows. Select that monitor explicitly:

[general]
xwayland_primary_output = "DP-1"

The setting accepts the same connector names and monitor identities as output sections. Run umbriel outputs to find them. Matching is case-insensitive. Use a monitor identity to follow a display between ports; use a connector to select a physical port. If a name matches several connected monitors with identical identities, Umbriel uses the first matching monitor in its internal layout order; use a connector to distinguish them.

Umbriel applies the choice on reload, when the monitor becomes available, and whenever its lazy Xwayland server restarts. The primary stays stable while focus or the pointer moves between outputs. If the chosen monitor is disconnected or disabled, Umbriel clears the X11 primary until it returns. Removing the setting or setting it to "" clears Umbriel’s previous selection once, then leaves X11 primary selection unmanaged. With the setting omitted from startup, Umbriel preserves externally selected primaries.

Output coordinates can be negative. Xwayland receives the layout translated to nonnegative coordinates, so the monitor at Umbriel’s [0, 0] need not be at Xwayland’s origin. focus_at_startup only places the cursor and does not select an X11 primary. Games that cache monitor information may need to be relaunched after changing the primary.

With nvidia_sync_workaround = true, Umbriel waits for GPU rendering to finish before presenting a composed output frame when the renderer uses the NVIDIA driver and the output has no explicit synchronization timeline. This can reduce flicker caused by unreliable implicit synchronization. Outputs with explicit synchronization continue to use GPU fences without this extra wait.

Waiting can cause stuttering or frame drops, especially when rendering takes longer than a refresh interval. Set nvidia_sync_workaround = false to disable the workaround if it causes those symptoms; synchronization-related flicker may return. Changes apply to subsequent composed frames on reload and survive renderer recovery. Capture synchronization is independent of this setting.

Use [drm] only when Umbriel should leave a GPU unopened in a native session. Omit the section for automatic GPU discovery. Changes require a restart.

[drm]
ignored_pci_addresses = ["0000:01:00.0"]
# ignored_devices = ["/dev/dri/by-path/pci-0000:01:00.0-card"]
KeyTypeDefaultDescription
ignored_devicesstring array[]Absolute card or render-node paths. Prefer stable /dev/dri/by-path links.
ignored_pci_addressesstring array[]PCI addresses in domain:bus:slot.function form.

Umbriel does not bind or unbind PCI drivers. Configure that lifecycle in libvirt or equivalent host tooling.

  • GPU exclusions affect native sessions only.
  • Startup fails when no allowed GPU can initialize.
  • Secondary GPUs must support the primary GPU’s DMA-BUF formats and modifiers.
  • Software rendering is incompatible with GPU exclusions.
  • With exclusions, WLR_BACKENDS supports only drm and optional libinput.
[environment]
ELECTRON_OZONE_PLATFORM_HINT = "auto"
SDL_VIDEODRIVER = "wayland"

These variables apply to Umbriel and commands started in its session. In a managed native session, they are also published to the systemd user manager for session services such as Noctalia. Nested sessions do not modify the host session environment.

Names must match [A-Za-z_][A-Za-z0-9_]*, and values must be strings. Umbriel owns its display, input-emulation, and session variables, so this section cannot override WAYLAND_DISPLAY, WAYLAND_SOCKET, DISPLAY, UMBRIEL_SOCKET, LIBEI_SOCKET, XDG_CURRENT_DESKTOP, XDG_SESSION_DESKTOP, or XDG_SESSION_TYPE.

Environment changes require an Umbriel restart. Fully quit and relaunch long-running applications that survived the restart.

Removing a key does not clear a value already published to the systemd user manager. Run systemctl --user unset-environment NAME to remove it immediately, or wait for the user manager to exit.

Run commands when the laptop lid closes or opens:

[events]
lid_close = "notify-send 'The laptop lid is closed!'"
lid_open = "notify-send 'The laptop lid is open!'"

Umbriel runs the command for the current lid state once during startup, after the compositor IPC socket is ready, then runs commands when that state changes. This also handles signing in while the lid is already closed or already open. If the system reports more than one lid switch, the combined state remains closed while any switch is closed. Device removal and re-addition during suspend do not repeat a command unless the combined state actually changed.

Logical output actions can remove the laptop panel from the desktop instead of merely powering it off:

[events]
lid_close = "umbriel msg output-disable eDP-1"
lid_open = "umbriel msg output-enable eDP-1"

Target-changing screencast actions ask for confirmation the first time they are used during an active single-source share. Dismissing the panel cancels only the pending action, so invoking one again asks again. Approval lasts until the share ends.

[screencast]
disable_dynamic_confirmation = false
KeyTypeDefaultDescription
disable_dynamic_confirmationboolfalseApply set and follow actions immediately without first confirming them. This can expose another window or output after an accidental key press.

Override an application’s registered shortcuts by its exact application ID and shortcut IDs:

[global_shortcuts."org.example.App"]
"push-to-talk" = "Mod+Shift+M"
"toggle-overlay" = ""

Values use the keyboard chord syntax from Keybinds; an empty string disables the shortcut. Mouse buttons, wheel events, modifier-only chords, and submaps are rejected. Invalid entries reject the configuration load, so a failed reload keeps the current configuration.

An override takes priority over the approved stored trigger and the application’s preferred trigger. It does not change the stored preference; removing it restores that preference. New shortcut IDs still require physical approval. Explicit overrides can assign printable keys, so choose them carefully.

Configured keybinds in the default submap, Ctrl+Alt+Escape, and VT-switch chords remain reserved. Live shortcut conflicts follow registration order. Reloading rebinds affected sessions and stops any held activation whose binding changed. Mod follows general.mod_key, including its native or nested default.

With no [[scratchpad]] entries, Umbriel provides one implicit scratchpad named default:

[keybinds]
"Mod+Shift+Space" = "window-move-to-scratchpad"
"Mod+Space" = "scratchpad-toggle"

To configure several scratchpads, give each one a unique name and include that name in its actions:

[[scratchpad]]
name = "terminal"
[[scratchpad]]
name = "music"
[keybinds]
"Mod+Space" = "scratchpad-toggle terminal"
"Mod+M" = "scratchpad-toggle music"

Defining a named scratchpad removes the implicit default. See Scratchpads for window assignment and behavior.

Umbriel honors idle inhibitors only while their application surface is mapped and visible. Switching away from its workspace, hiding it in a scratchpad, disabling its output, or locking the session suspends the inhibitor until the surface becomes visible again.