- C 56.6%
- Lua 39.3%
- Python 2.1%
- JavaScript 0.7%
- GLSL 0.6%
- Other 0.5%
| .gitea/issue_template | ||
| .regression | ||
| extensions | ||
| protocols | ||
| scripts | ||
| SHADER_EXAMPLE | ||
| shells | ||
| sounds | ||
| src | ||
| tools | ||
| .gitignore | ||
| .mailmap | ||
| .mp4 | ||
| AGENTS.md | ||
| client.h | ||
| compile_commands.json | ||
| config.def.h | ||
| config.mk | ||
| config_uwwm | ||
| glsl-chk | ||
| LICENSE | ||
| LICENSE.dwm | ||
| LICENSE.sway | ||
| LICENSE.tinywl | ||
| Makefile | ||
| Makefile.asan | ||
| README.md | ||
| shell.nix | ||
| sources.conf.example | ||
| util.c | ||
| util.h | ||
| uwwm | ||
| uwwm-04a23747.o.tmp | ||
| uwwm-05c74ef6.o.tmp | ||
| uwwm-clip | ||
| uwwm-e66ed5fa.o.tmp | ||
| uwwm.1 | ||
| uwwm.c | ||
| uwwm.desktop | ||
| uwwm_audio.c | ||
| uwwm_audio.h | ||
| wp-wcopy.frag | ||
UWWM - Unlimited Wayland Window Manager
UWWM is a fast Wayland compositor built on wlroots that treats your desktop as a real 3D space instead of a grid of fixed rectangles.
Windows sit on an infinite canvas you pan, zoom, and lean into. The camera has weight. Windows have depth: they float above the wallpaper, tilt as you move them, and drop shadows that sell the gap. No workspace boxes, no columns deciding your layout, no daemon just to show a clock.
- A true 3D desktop. Parallax depth, spring physics, a camera you fly around.
- Live settings. Most changes apply the moment you save the file. No rebuild, no logout, nothing closes.
- Your wallpaper sets your theme. Borders, glow, shadows, the bar and the cursor take the palette of the picture you are looking at, and change colour over time instead of snapping. GTK, Qt, KDE and your terminal can follow the same palette.
- A wallpaper browser built in. Browse your folders and five wallpaper sites on the same scrolling belt, rate and tag what you find, and watch it play if it is a video.
- Built for games. Fullscreen windows go straight to the display, bypassing the compositor, so you get the frame rate your hardware can actually deliver. HDR included.
- Yours to take apart. One readable C file, a Lua layer for the on-screen interface, and no mandated workflow.
Getting UWWM
Dependencies
Required:
wlroots(built with the libinput backend)wayland,xkbcommon,libinput,dbusgrim(screenshots)dragon-drop, the drag source behind the deck's copy verbs. The build stops with a clear message if it is missing. Packagedragon-dropon Arch and Debian/Ubuntu,dragonon Fedora. If it is installed under another name, passmake DRAGON_PROG=/path/to/the/program.cava, which publishes the audio levels that drive the reactive shader effectsgdk-pixbuf, which decodes album art, so JPEG and WebP covers work as well as PNGundefined-mediumfont (the default face the config references)
wl-copy is optional. The deck's own uwwm-clip is the primary clipboard tool
because it offers a file under several types at once, and wl-copy is the
fallback on a machine without it.
curl is used to fetch album art published as an http or https URL. Without it those covers
simply do not appear, and nothing else is affected.
Recommended for the built-in workflows:
wmenu, the application launcher and drag-to-spawn menusatty, to annotate screenshots as soon as you take themwf-recorderfor video,ffmpegfor GIF capture
For X11 applications:
UWWM prefers xwayland-satellite, which runs X11 programs as native Wayland surfaces with
correct positioning. If it isn't found at startup, UWWM falls back to its built-in XWayland
server. Building with that internal support needs libxcb, libxcb-wm, and a wlroots
built with X11 enabled.
Building
make
sudo make install
This installs the compositor and its companion runtime module, which loads at startup.
make also builds a separate debug pair (uwwm-dbg and uwwm-debg.so) carrying the
diagnostic tracing. The regular uwwm binary has none of it.
TODO: the shell (control center, HUD, widgets) is being split into its own repository and added back as a submodule. Until then, install it by copying the
shells/directory into~/.config/uwwm/. These instructions get updated once the repo is public.
Shells are documented in their own file: shells/README.md.
Quick reference
Mod is the Super / Windows key.
Camera and canvas
| Input | Action |
|---|---|
| Left click + drag on empty space | Pan the camera, with momentum |
Mouse wheel on empty space, or with Mod |
Zoom in and out |
Mod + - / Mod + = |
Step zoom out and in |
Mod + A |
Fly the camera back to the origin |
Mod + M |
Cycle the workspace layout mode (zones) |
Windows
| Shortcut | Action |
|---|---|
Mod + Arrow keys |
Move focus across the canvas |
Mod + Ctrl + Arrows |
Slide the focused window across the canvas |
Mod + Shift + Arrows |
Resize the focused window |
Mod + Space |
Float or tile the focused window |
Mod + Shift + F |
Toggle fullscreen |
Mod + F |
Toggle true fullscreen, where the buffer goes straight to the display |
Mod + Q |
Close the focused window |
Mod + I |
Cluster mode, to see and edit window groups |
Free-form windows line up with each other, but the window never leaves the cursor: the
alignment is measured while you drag and shown as a guide line in snap_guide_color, and the
button release is what moves the group to it, over snap_settle_ms (600 ms) with an ease-in-out
ramp. Pickup distance is zone_snap_threshold (16 px, divided by zoom so it means the same
distance at any scale), and it only engages where the windows actually overlap on the other
axis. It sticks window to window, never to invisible layout lines, so it stays predictable.
Holding mod over the focused window also puts a ring at its centre. Hover that ring and a menu
opens in place of the corner brackets: this window or whole stack, then which monitor,
then which workspace: all nine at once, each one a chip with an SDF label. Sending something
is animated rather than instantaneous: on the same monitor the window or stack slides across the
canvas to the workspace it now belongs to while the camera follows it; between monitors it lifts
off toward the camera and lands down into place on the other one, or sinks away and lands when
you send it down the stack. Each step is send_anim_ms (600 ms).
Chrome text is drawn at helper_font_size × corner_zone_text_scale (1.5) and never shrinks below
that on screen: below zoom 1.0 the world gets smaller but the text holds its size, so the labels
stay readable when you zoom out to look at the whole canvas.
The hidden workspace
| Shortcut | Action |
|---|---|
Mod + H |
Show or hide the special workspace |
Mod + Shift + H |
Send the current window to it |
Mod + Ctrl + H |
Cycle between special workspaces |
What's in there recedes when you put it away: it dims, desaturates, and blurs, so you always know which side of the wall you're on.
Launching and placing
| Shortcut | Action |
|---|---|
Mod + Return |
Terminal |
Mod + P |
Application launcher |
Mod + Ctrl + Left click + drag |
Drag out a region. The next window opens exactly there |
Escape |
Cancel an in-progress region drag |
Effects
| Shortcut | Action |
|---|---|
Mod + S / Mod + Shift + S |
Cycle / toggle background effects |
Mod + C / Mod + Shift + C |
Cycle / toggle cursor effects |
Mod + W / Mod + Shift + W |
Cycle / toggle window effects |
Capture and session
| Shortcut | Action |
|---|---|
Print |
Screenshot with an interactive crop, opened for annotation |
Ctrl + Print |
Start or stop video recording |
Shift + Print |
Start or stop GIF capture |
Mod + Shift + Q |
Quit UWWM |
| Session pill in the bar (left of the bell) | Open the session manager |
A recording indicator stays on screen while a capture is running, so you can't forget one.
Configuring UWWM
Two layers. You'll probably only need the first.
Runtime settings live in ~/.config/uwwm/config.conf: appearance, animation feel,
border styles, colours, effects, HDR, per-monitor options. UWWM watches the file, so
saving applies changes immediately without restarting or interrupting anything. Per-monitor
sections override the defaults, so one display can be HDR while another is SDR, with
different zoom and layout behaviour.
The on-screen interface, meaning the control center, status widgets, clock and media card, is written in Lua and reloads the same way. Almost every runtime setting has a slider or toggle there, so you can watch it change instead of guessing at numbers in a file.
Build-time settings, the default keybindings and compiled-in defaults, live in
config.h in the traditional upstream manner. Note that config.h is generated once from
config.def.h and is not re-copied on later builds, so edit config.h itself. Changing it
needs a rebuild, and the running session picks it up on next start.
The compositor also listens on a socket at /tmp/uwwm_ipc, so external scripts and bars can
drive it. See Scripting UWWM.
Features
Each entry is marked with what kind of thing it is, how much it matters, and how much of it you can already get somewhere else.
- WM: what the compositor does to windows and to your session.
- Movement: how windows and the camera are placed, moved and resized.
- Aesthetics: how the desktop looks.
- Extension: Lua, plugins, and the tools around the compositor.
Importance is how central the feature is to using UWWM day to day. Uniqueness is how hard it is to find the same thing in another compositor: 5 means nobody else really does it, 1 means plenty do.
The 3D canvas
Category: Aesthetics Importance: 5/5 Uniqueness: 5/5
Windows are placed in a concentric, non-overlapping grid on an infinite plane rather than trapped inside one monitor's rectangle. Panning has momentum, and everything (windows, the camera, fullscreen transitions) moves on spring physics with a little overshoot and settle, so the desktop feels handled rather than rendered. Windows bank away from the direction they are moving, with a soft ceiling rather than a clamp, so a flick leans harder than a drag but the two stay distinguishable.
With window parallax on, windows gain real depth. They lean as the camera moves, separate from the wallpaper behind them, and their shadows shift to sell the gap. Cursor and background effects share the same spatial model, which is why the screen reads as one scene instead of a stack of layers.
Where a new window lands
Category: WM Importance: 4/5 Uniqueness: 4/5
A new window first tries to attach to the edge of the group you are already working in, full-edge before partial-edge, so a column stays a column. That is the same cluster rule driftwm uses. When more than one edge is legal it picks the one with the most open space still beyond it, rather than simply the nearest, so a row of same-size windows grows into the free area instead of stacking straight downward until it runs out of screen.
If no clean attachment is legal at all, the compositor enumerates the free rectangles in the workspace, taking their corners from the windows already there plus the zone frame, and drops the window into the largest open space, with a small distance penalty to keep it near the group you are working in.
A small amount of randomness rides both choices, deliberately small. With same-size windows a pure score would pick the identical edge every time, which is what made the layout feel boring; the jitter keeps two spawns of the same app from resolving to the same spot without making the placement look arbitrary.
Nothing ever lands on top of something else: a candidate that overlaps an existing window, or that cannot fit its own width and height in the clear run beside it, is rejected outright.
Workspace zones (Mod + M)
Category: Movement Importance: 4/5 Uniqueness: 3/5
Zones split the canvas into named, resizable regions that behave like traditional tiling areas without giving up freeform placement. Cycle the layout mode to rearrange everything at once, or drop a window into a zone and let it fit.
Window clustering (Mod + I)
Category: Movement Importance: 4/5 Uniqueness: 4/5
Cluster mode shows the relationships between your windows so you can edit them by hand.
- Badges appear above windows. Click a badge's O handle and drag to another window to link them.
- Linked windows move together, proportionally, across the canvas.
- Click the X at a link's midpoint to cut it.
- Click a cluster's name label to rename it.
- A badge shows how many notifications a window has received. Click it to expand the list, with icons and summaries.
Corner action zones
Category: Movement Importance: 3/5 Uniqueness: 4/5
Hold the modifier over a focused window and four small action targets appear on
its corners. By default that is set anchor (top-left), grab one (top-right),
move stack (bottom-left) and resize stack (bottom-right). Which action
sits on which corner is yours: corner_zone_tl, corner_zone_tr,
corner_zone_bl and corner_zone_br take set-anchor, grab-one,
move-stack or group-resize.
What you see, so you never have to guess where you are pointing:
- The corner you are on fills in and pulses. The others stay quiet.
- The box that registers is the box you can see, at every zoom level.
- Below zoom
1.0the targets grow faster than the canvas shrinks, three times the configured size at0.5zoom, so zooming out never makes them harder to hit. - Where two targets crowd, the one nearest the pointer wins.
- A window that is the anchor of its stack carries a small steady pin, so that state is visible instead of something you have to remember.
- While you drag, every window that would travel with the one you are holding is outlined. Release and that is exactly what happens: the outline is decided by the same rule the release uses.
| Key | Default | Meaning |
|---|---|---|
corner_zones |
1 |
Switch the four corner targets on or off. |
corner_zone_size |
48 |
Target size in canvas pixels, before the zoom scaling above. |
corner_zone_tl / _tr / _bl / _br |
set-anchor / grab-one / move-stack / group-resize |
Which action lives on which corner. |
corner_zone_min_zoom |
0.06 |
Below this zoom the targets switch off entirely. A last-resort guard, not a limit you will normally reach. |
spatial_menu_open_ms |
500 |
How long the pointer must rest on the window's centre dot before the workspace menu opens. |
spatial_menu_close_ms |
500 |
How long it may stay outside the safe box before that menu dismisses. |
spatial_menu_hitbox_scale |
3.0 |
How far outside the menu the safe box reaches. |
Shader pipelines
Category: Aesthetics Importance: 3/5 Uniqueness: 4/5
Three independent GLSL fragment-shader pipelines run over the desktop.
- Background effects process your live wallpaper (
awwworswww): bloom on bass hits, edge-detection outlines that sharpen artwork, directional smear, and surface lighting computed from the image itself. - Cursor effects replace the static pointer with a physical one. It tilts, rotates, stretches with velocity, magnifies when you flick it, and scales up several times when you shake it, so you can find it across multiple monitors.
- Window effects draw the neon edge glow, highlights, and motion trails you see when windows move.
Defaults are built into the compositor and written out to ~/.config/uwwm/shaders/ on first
run, so you can start from something that already works. Shaders reload live. UWWM
checks each shader directory once a second (shader_hotreload_interval_ms, 0 to turn it
off), so saving a file applies immediately with no restart and nothing closing. If a shader
fails to compile, that pipeline falls back to its built-in source instead of breaking, so a
typo costs you the effect and not the session.
Audio reactivity ships with the compositor itself: a dedicated capture thread reads the
default monitor with ~10 ms of requested latency and a 2048-point Hann FFT feeds the same
64-band publish path the shader pipelines consume - no external analyser process and no FIFO
hop, with the audio-to-bins latency measured at a fraction of the external cava route.
audio_analyzer = internal (the default) or audio_analyzer = cava in config.conf picks the
pipeline; the cava route stays available for setups that tune their own analyser, and UWWM
still writes a ready-made ~/.config/cava/config_uwwm for it if you choose that path. The
capture thread only starts when the internal pipeline is selected, monitors the default sink,
and falls back to the FIFO path automatically if PulseAudio setup fails.
If you pick audio_analyzer = cava, start it after login and the pipeline is live:
cava -p ~/.config/cava/config_uwwm &
The generated file follows your system default output. Uncomment the source line inside it
to bind a specific device. UWWM never overwrites that file once it exists, so your edits
survive upgrades.
SHADER_EXAMPLE/ in the source tree is the documentation side of this: every uniform of all
three pipelines, the audio frame protocol, a worked audio-visualizer example, and a list of
effects worth trying. Start there if you are writing your own shader rather than tuning one.
MusicFX is a built-in music layer, not a shader you have to write. It draws glowing vertical lines that sit in the blurred margins around your wallpaper and react to whatever is playing.
It is a compositor pass, the same kind of thing as WallpaperFX: one fullscreen quad, one shader, one framebuffer. Nothing is drawn per line, and nothing is uploaded per frame except a handful of numbers, so it costs one pass regardless of how much is happening.
What it does:
- Framed (the default). The lines live in the blurred margins either side of a
contain-blurwallpaper and are masked so they can never cross the picture itself. Turnmusicfx_frame = 0and they spread across the whole panel instead, rising from the bottom. - It jumps on the beat, then settles. The lines are not driven by the volume directly. A small spring chases the level, so a hit snaps them out past where they settle and they ease back. That overshoot is what makes it look like flow rather than a bar meter.
- A sheen runs down the lines on a bass drop. Each detected drop sends one bright band sweeping from the top of the panel to the bottom.
- It is still alive when nothing is playing. Quiet, dim, slow sway. It does not
switch itself off. Only
musicfx = 0stops it. - It wears your wallpaper's colours by default, and they drift slowly.
| Key | Default | What it does |
|---|---|---|
musicfx |
1 |
Master switch. |
musicfx_style |
electric |
electric is the lines on their own. fire, particles and shapes add floating particles, and shapes draws circles, rings, stars, hearts, polygons and dashes. mixed runs the lines and particles together. |
musicfx_frame |
1 |
Keep the lines in the contain-blur margins and off the artwork. |
musicfx_count |
4 |
How many lines, 1–8. |
musicfx_thickness |
2.6 |
Line core width in pixels. The glow halo scales with it. |
musicfx_speed |
0.7 |
How fast the waves travel along the lines. |
musicfx_alpha |
0.85 |
Overall opacity. |
musicfx_audio |
1.0 |
How much the spectrum moves the lines at all. 0 leaves them swaying on their own. |
musicfx_particles |
32 |
How many particles are alive at once, 0–48. |
musicfx_density |
1.0 |
How fast particles are emitted. |
musicfx_palette |
1 |
Use the wallpaper's palette. 0 uses musicfx_color instead. |
musicfx_color |
#FF5C3DFF |
The colour to use when musicfx_palette = 0. |
Every one of these is read live, so editing config.conf changes the layer immediately.
No restart.
HDR and colour
Category: Aesthetics Importance: 5/5 Uniqueness: 4/5
UWWM drives HDR through the display hardware rather than through the compositor, which is what keeps fullscreen content fast.
- Per-monitor HDR in PQ or HLG, detected from what the display actually reports.
- SDR white level sets how bright ordinary windows sit inside an HDR signal. This is the single most useful setting for making a desktop look right on an HDR panel.
- Desktop gamma, a shadow lift that raises crushed near-blacks, and highlight knee controls for both transfer functions.
- Brightness, contrast, and saturation grading, applied on the display side.
- Colour management reports honest capabilities to applications, so a game or video player is told what your panel can actually reach.
Because all of it happens on the display hardware, it also applies to directly-scanned-out games. You get HDR and colour grading for free, with no frame cost.
ShellFX
Category: Aesthetics Importance: 3/5 Uniqueness: 3/5
The whole on-screen interface is scriptable, and it runs inside the compositor. No bar daemon, no layer-shell client, no separate process to configure and keep alive.
A shell is a directory of Lua files under ~/.config/uwwm/shells/. The compositor loads it,
gives you a GPU-backed drawing surface per monitor, and calls your functions each frame:
shells/
default/ the shipped shell: bar, control center, clock, media card
init.lua entry point, returns a table of callbacks
widgets/ optional sub-modules
fallback/ a minimal HUD that loads if your shell errors
The callback you care about first is on_render(monitor, width, height, dt). Draw with the
supplied primitives (rounded rects, gradients, circles, text, icons, glass panels, plus 3D
versions of all of them that lean with the desktop), and read live state straight from the
compositor: focused window, camera position and zoom, cursor, audio levels, CPU and memory,
Wi-Fi and Bluetooth, media player metadata. You can also drive the compositor back: spawn
programs, switch workspaces, change zoom, set volume.
Saving a file reloads it. Nothing restarts, nothing closes, and if your shell throws the compositor falls back to the built-in HUD instead of leaving you with a dead screen. That makes it safe to experiment live, which is the point.
Full reference, including every function signature and a copy-paste skeleton, is in shells/README.md. It is written to be handed to an LLM and used to build a shell from scratch.
ScreenFX
Category: Aesthetics Importance: 2/5 Uniqueness: 3/5
A compositor-side effect layer over the composited desktop, rather than per window. All six work: vignette, scanlines, film grain, chromatic aberration, bloom, and motion blur.
Motion blur is directional rather than a crossfade. A velocity buffer records how far each window actually travelled between frames, so a moving window smears along its own axis while a still desktop stays sharp, and the camera's own pan and zoom is folded in so the whole view blurs together when you move around.
Every strength ships at 0.00, so the pass is skipped entirely until you raise one. That
means it costs nothing when switched off, and it never runs in front of a fullscreen game,
which keeps direct scanout intact. Colour and HDR are complete and independent of this.
Per monitor. Each display has its own strengths in its [monitor.*] section, so one panel
can be graded heavily and another left alone. A key that is absent inherits [general], and a
key that is present and 0 is genuinely off for that panel, which is what lets you switch an
effect off on one display while it stays on everywhere else. The ScreenFX page in the control
center previews each effect on a simulated desktop as you move the sliders, and a SYNC TO ALL
button copies the selected monitor's whole grade to every other output.
Performance
Category: WM Importance: 5/5 Uniqueness: 4/5
UWWM tries hard to stay out of the way of anything that cares about frame timing.
- Direct scanout with a hardware cursor. When a window fills the display, its buffer goes straight to the screen and the compositor steps aside. No extra copy, no composition cost. The display hardware makes that call, so any application presenting a compatible fullscreen buffer gets it, not just games. The pointer stays live over scanned-out content: it is driven through the Wayland cursor object onto the KMS cursor plane, so a fullscreen game keeps both its zero-copy path and a visible mouse, and the CursorFX shader cursor and the plane never draw at the same time. If an application offers a cursor image the compositor cannot upload, the theme pointer is used instead.
- The interface draws in one call. Every panel, border and glyph the shell draws is
collected and submitted as a single instanced draw, and the instance data is written
straight into GPU memory instead of being re-uploaded each frame. Both can be switched
off in
config.conf(shell_batching = 0,shell_batch_zerocopy = 0) if a driver ever disagrees. - Tearing option. Allow unsynchronised presentation for the lowest possible latency, when you'd rather have every frame now than wait for the next refresh.
- Adaptive sync (VRR) per monitor, where the display supports it.
- Idle throttling. The interface, physics, and animation loops drop to a low rate when nothing is moving and wake instantly on input, so an untouched desktop costs almost nothing.
- Presentation-time pacing. Frames are gated on the display's own presentation clock rather than on a fixed tick rate, so a 165Hz panel is asked for at most 165 frames a second. Damage still wins, a window that repaints is composited immediately.
- Viewport culling. Windows that are on your current workspace but scrolled or panned clean off the display are skipped entirely, so they cost no geometry, no border render and no texture upload.
- Off-screen frame throttling. Applications only get a frame callback when their window is
actually visible, otherwise at
offscreen_frame_hz, default 15. That is what stops a browser two workspaces away from rendering pixels nobody can see. Set it to 0 for full rate. - Batched drawing. The interface groups its draw calls into single GPU submissions instead of one per element.
- Window velocity lean. Dragging a window banks it away from its direction of travel,
tuned by
window_move_tilt_degin[3d_window], the soft ceiling in degrees, andwindow_move_tilt_knee, the screen px/s that reaches half of it. It straightens the moment a snap engages, because a rotated edge cannot line up with an axis-aligned guide. - Input is dispatched before drawing, with no forced compositor latency.
Media, clock, notifications, coordinates
Category: Aesthetics Importance: 3/5 Uniqueness: 2/5
All drawn natively, with no extra process.
- Media player. A glassmorphic card driven over D-Bus, with cover art and a progress bar
that tracks seeking in real time, in a compact or wide layout. Cover art is decoded by
gdk-pixbuf, so JPEG, WebP and AVIF work as well as PNG, and an
httporhttpsart URL from a server-backed player is fetched in the background and cached, never on the render thread. Target it at one monitor or all of them, put it behind your windows or in front, or expose it as an ordinary movable window. - Clock. Configurable face, per-monitor placement, three depth layers.
- Notifications. Handled internally over D-Bus, with a stealth mode that tells you something arrived without putting the content on screen, and an option to prefix the window that caused it.
Screen capture and recording
Category: Extension Importance: 3/5 Uniqueness: 3/5
Screenshots, video, and GIF capture are bound out of the box and route through grim,
wf-recorder, and ffmpeg. Screenshots open a crop selection and hand straight to satty
for annotation. UWWM also speaks the ext-image-capture protocol directly: wlr-shot (or any
client of that protocol) can capture the whole output, a region, or a single window by
listing toplevels and passing an identifier. Output capture is live today; window capture
is wired to the same protocol (a toplevel capture request supplies the window's scene node
as its source) and is pending verification.
Remembering your session
Category: WM Importance: 4/5 Uniqueness: 5/5
UWWM keeps a picture of how your desktop was arranged and can put it back.
The session manager is the pill in the bar, just left of the notification bell. It lists saved sessions newest first; open one and you see the windows inside it: which program, which monitor, where on the canvas, how large, and whether it was floating, fullscreen, or on the hidden workspace.
- It saves by itself. A checkpoint is written on a timer and whenever windows change, so there is nothing to remember to do before a crash.
- Restore puts windows back where they were: same monitor, same place on the canvas, same zone and grid cell, same floating / fullscreen / hidden state. It also remembers which layout each workspace was in - free canvas, grid, strip, diagonal, or master-stack - per monitor, so a workspace you had set to STRIP comes back as STRIP instead of packing the restored windows into the wrong layout and landing them off their cell. Programs that are no longer running get relaunched into the slot they used to occupy.
- It asks before it changes anything. When UWWM starts and there is a saved session to go back to, a card drops down in the middle of the screen and asks whether to bring those windows back. You can answer once, choose Always restore, or tell it never to ask again - all three are switchable later in the session manager's OPTIONS tab.
- Deleted sessions go to a trash, not the void. A cleared session can be brought back until you empty the trash, and every destructive button counts down three seconds first, so one stray click cannot erase a week of work.
- Recovery when rendering stumbles. UWWM watches for its own frame loop going quiet and will rebuild the rendering path instead of leaving you staring at a dead screen. Attempts are capped, so genuinely broken hardware is not retried forever.
- Programs can describe what was inside their windows. Geometry is only the
shell. An application may hand UWWM a small block of its own state, stored
untouched next to the window it belongs to. The browser extension in
extensions/, for example, carries your open tabs and which windows were incognito.
All of it is off by one switch and tunable in the config file:
| Key | Default | Meaning |
|---|---|---|
session_manager_enabled |
1 |
Master switch for the session store. |
session_autosave_sec |
300 |
How often a checkpoint is written; 0 turns the timer off. |
session_cap_sessions / _subsessions / _windows |
3 |
How much history is kept before the oldest is dropped. |
session_unlimited |
0 |
Ignore the caps. |
session_incognito |
0 |
Stop recording the desktop entirely. Nothing is written while it is on. |
session_restore_on_crash |
0 |
Restore the newest session automatically after an unclean exit. |
session_restore_prompt |
1 |
Ask, on startup, whether to bring the last session back. |
session_restore_on_start |
0 |
Restore the last session on startup without asking. |
session_restore_focus |
1 |
Default for the restore prompt: put the camera and the focused window back where the snapshot caught them. Off means everything comes back in the background. |
session_restore_merge |
0 |
Default: fold the saved windows into the session you are in, instead of switching to the saved one. |
session_restore_close |
0 |
Default: afterwards, close live windows the saved session never had. |
session_restore_incognito |
1 |
Relaunch the browser with --incognito so its worker can put private windows back. |
session_recovery_timeout |
20 |
Seconds the startup question waits before answering itself; 0 waits forever. |
session_recovery_default |
1 |
What the timeout falls back to: 0 nothing, 1 last session, 2 default session. |
session_capture_audio |
1 |
Carry UWWM's own audio-reactive tuning (analyser, attack/release, band powers) with the session. Per-application volume, mute and routing belong to WirePlumber, which already persists them, so UWWM does not duplicate that policy. |
session_window_autosave_sec |
0 |
Per-application checkpoints, for apps that restore on their own. |
recovery_watchdog_sec |
5 |
How long rendering may go quiet before recovery starts; 0 disables it. |
recovery_max_attempts |
3 |
Recovery attempts before UWWM gives up. |
Wallpaper thumbnails (Spec 04)
Category: Aesthetics Importance: 3/5 Uniqueness: 4/5
| Key | Default | Meaning |
|---|---|---|
wall_thumb_dir |
~/.config/uwwm/wallpaper/thumbs |
Where generated thumbnails are kept. |
wall_thumb_size |
1280 |
Thumbnail max edge, px. It is part of the cache key, so changing it starts a fresh generation pass instead of mixing sizes. |
wall_thumb_tex_cache |
64 |
How many thumbnails stay resident as GPU textures. Sized for the selector's visible slice window plus the browsers. |
wall_thumb_max_mb |
512 |
On-disk budget; past it the oldest thumbnails are deleted. |
wall_thumb_png_level |
6 |
PNG compression, 0 (fastest, biggest) to 9 (smallest, slowest). PNG is lossless, so this never changes how sharp a card looks. |
wall_thumb_micro_dir |
~/.config/uwwm/cache/thumbnails |
Where the 32 px blur-in previews are kept, so they survive a restart. |
Thumbnails are keyed to the file itself, by what it contains and when it last changed, rather than by its path: replace a wallpaper and its thumbnail is rebuilt, rename one and it is kept. Generation runs on its own thread, so opening the selector never decodes anything on the render path, and an image that is not ready yet draws a placeholder until it is.
Drive it with uwwm-ctl wall thumbs scan <dir>, status, watch or stop.
A card that has no thumbnail yet does not draw an empty box: it draws a 32 px version of the same picture, deliberately soft, so the card reads as the artwork out of focus and then sharpens when the real thumbnail lands. Those small versions exist on disk only to carry across a restart. Inside a session they live in RAM.
The first pass through a folder is always the slower one, because every card still needs a GPU upload and an upload is a synchronous copy. Uploads are capped by bytes per frame rather than left to whatever happens to be on screen, so a page of cards arrives over several frames instead of in one stutter, and scrolling back over the same images is free because their textures are already resident.
Per-monitor wallpaper (Spec 04)
Category: Aesthetics Importance: 4/5 Uniqueness: 3/5
Each display gets its own wallpaper, in a section named after the output name, never an output index:
[wallpaper.DP-1]
path = ~/Pictures/wallpapers/night.png
mode = cover # cover | contain | contain-blur | stretch | tile | tile-infinite | mirror | center
The name is persistent identity. An index changes the moment a panel is unplugged, a dock re-enumerates, or a display is added in the middle; a name does not. An entry also survives its panel being away: unplug DP-2 for the whole session and the wallpaper you set for it is still there when it comes back.
At runtime the selector is the source of truth, and uwwm-ctl wall save
writes that state back into config.conf (replacing the previous
[wallpaper.*] block and leaving the rest of your file untouched, comments
and ordering included).
| Command | Meaning |
|---|---|
uwwm-ctl wall list |
every configured output, its wallpaper, and whether it is currently connected |
uwwm-ctl wall monitors |
connected outputs and what each one resolves to |
uwwm-ctl wall get <name> |
the wallpaper for one output |
uwwm-ctl wall set <name> <mode> <path> |
set one output |
uwwm-ctl wall apply-all <mode> <path> |
same wallpaper on every connected output, one entry each |
uwwm-ctl wall clear <name> |
drop an entry |
uwwm-ctl wall save |
write the current state into config.conf |
Fitting a wallpaper to a screen
Category: Aesthetics Importance: 3/5 Uniqueness: 3/5
mode = takes one of these. UWWM bakes the choice into the wallpaper texture,
so what is on the panel is exactly what you picked, at any zoom, with no
letterboxing surprises when you move the camera.
| Mode | What it does |
|---|---|
cover |
Fills the panel completely and crops whatever overflows. The default, and the right answer most of the time. |
contain |
Shows the whole picture, letterboxed. |
contain-blur |
Shows the whole picture over a blurred enlargement of itself instead of flat bars. Best option for a portrait image on a wide panel. |
stretch |
Forces the picture to the panel exactly. Distorts it. |
tile |
Repeats the picture at its own size, pinned to the panel. |
tile-infinite |
Repeats it and lets the pattern run across the whole workspace grid. Pan the camera and the tiles scroll with you. |
mirror |
Repeats it alternating flip, so the seams line up. |
center |
One copy at its own size, in the middle, cropped if it is larger than the panel. |
wall_tile_px (default 0, meaning the file's own dimensions) sets the tile
cell in pixels along the image's long edge, so a huge photograph can tile at a
sane density. For tile-infinite the cell is snapped to a size that divides the
panel exactly, which is what makes the repeat seamless when the grid wraps.
To correct one artwork that is on its side, use the flip control in the
selector (none / upside down / left / right). The choice is remembered per file
in ~/.config/uwwm/wallpaper/marks.conf and applied whenever that file is
decoded, so it stays fixed for every wallpaper you pick afterwards.
Per-monitor folders
Category: Aesthetics Importance: 3/5 Uniqueness: 3/5
By default the wallpaper folder and its rotation are desktop-wide: every panel pulls from the same set. Turn this on and each output keeps its own folder, interval, order and rotation.
| Key | Default | Meaning |
|---|---|---|
wall_per_monitor_folders |
0 |
1 gives every display its own folder set instead of sharing one. |
The same switch is in the selector under OPTIONS > ENGINE AND OUTPUT. With it on, binding a folder while the selector is open on one panel changes that panel only, and the deck lists that panel's own images.
Extensions
Category: Extension Importance: 4/5 Uniqueness: 4/5
Optional helpers that live outside UWWM and tell it what is inside a window. They are not required and nothing in the compositor depends on them.
extensions/browser/: a browser extension plus one tiny helper program. It records which tabs were open, in which window, in what order, and which windows were incognito, so a restore gives you back the browsing session and not just a browser window.extensions/legcord/: makes a Discord notification carry the exact channel and message, so clicking OPEN in UWWM lands you on the message instead of merely raising the app.
Each folder's README.md says what it does, how to install it, and what its
limits are.
Edge panning
Category: Movement Importance: 3/5 Uniqueness: 4/5
Dragging or resizing near a display edge pans the camera at a controlled rate so the action stays on screen, with configurable threshold and acceleration, and protection against the runaway-expansion feedback loop this feature is notorious for. An option decides whether panning happens at boundaries you share with another monitor.
Scripting UWWM
Category: Extension Importance: 4/5 Uniqueness: 4/5
A socket at /tmp/uwwm_ipc takes simple space-separated commands, so bars, keybinds, and
scripts can drive the compositor without an embedded interpreter.
uwwm-ctl is the command-line client for it: uwwm-ctl windows, uwwm-ctl active,
or any verb below verbatim.
- Camera and layout:
recenter,pancamera <0-3>,zoomcamera <factor>,view <1-9>,tag <1-9> - Windows:
focusdirection <0-3>,focusstack <±1>,togglefloating,togglefullscreen,killclient - Effects:
toggle_shader_manager/_cursor/_window,cycle_manager_shader/_cursor_shader/_window_shader,togglehelpers - Interface shell:
get_shells,get_shell_status,switch_shell <name>,debug_shell - State:
get_coords,get_active_window,get_clients,get_monitors - Sessions:
session_snapshot [label],session_restore <id>,session_trash <id>,session_track <app_id> [interval_sec] [count],session_untrack <app_id>,session_register <app_id> [name] [max_windows],session_state <app_id>,session_state_set <app_id> <one-line text> - System:
spawn <command>,quit
Two examples:
uwwm-ctl active # the focused window: appid, title, geometry
uwwm-ctl pick # click any window with the mouse: appid, title, tags, monitor
uwwm-ctl windows # every window and what UWWM calls it
uwwm-ctl view 3
VR
Category: WM Importance: 4/5 Uniqueness: 2/5
When a headset is connected, UWWM recognises its non-desktop display modes and leases the hardware directly to SteamVR. Plugging in is the whole setup.
Fullscreen games and aspect ratio
Category: WM Importance: 5/5 Uniqueness: 4/5
Fullscreen content can either stretch to fill the panel or keep its native aspect ratio with clean black bars. It's a per-monitor choice, useful for older titles and handheld-mode resolutions.
Copying and dragging a file out
Category: Extension Importance: 4/5 Uniqueness: 4/5
Right-click a card and choose COPY IMAGE or COPY VIDEO. The file goes on the clipboard AND into a drag window at the same time, because different programs want different things and you should not have to know which.
Why both. A terminal wants the bytes. A file manager wants a link. Discord and
other chat apps want a real dropped file, and a clipboard holding one image type
answers none of those questions at once. UWWM's own uwwm-clip owns the
selection and offers the file under its own type, a JPEG version, a uri-list and
the plain path, so the target can take whichever one it actually asks for.
dragon-drop supplies the drag alongside it.
Multiple files go to the drag only, in one offer holding all of them. A multi-file clipboard selection has no honest single type, and copying them one at a time would throw each one away as the next arrived.
| Key | Default | Meaning |
|---|---|---|
wall_drag_drop |
1 |
0 keeps the clipboard offer and never opens a drag window. |
The toggle is on the deck's OPTIONS page, in the ENGINE AND OUTPUT card, as DRAG ON COPY.
The wallpaper deck
Category: Aesthetics Importance: 5/5 Uniqueness: 5/5
A wallpaper browser built into the compositor. Open it by clicking the wallpaper pill in the bar (immediately left of the session pill). It is not a file picker: it is a scrolling belt of cards you can sort, filter, favourite, rate, tag and delete without leaving the desktop.
How it works. Every card is drawn by the compositor's own GPU shell, so scrolling the deck is as smooth as moving a window. Thumbnails are made on a background thread. Each one is keyed to the file itself, by what it contains and when it last changed, rather than by its name: replace a wallpaper and its thumbnail is rebuilt, rename one and it is kept. A card whose thumbnail is not ready yet shows a deliberately soft 32 px version of the same picture, then sharpens when the real one lands.
What you use it for. Changing wallpaper becomes something you browse rather than something you configure. Sort by name, date, random or rating. Filter to favourites. Delete a bad one with a two-second confirm. Right-click a card to copy the image to the clipboard, copy its path, copy its tags, mark it safe or NSFW, edit its tags, or pin it to Pinterest.
| Key | Default | Meaning |
|---|---|---|
wall_folder |
(none) | A folder to browse. Repeat the key for more than one folder. |
wall_rotation |
0 |
1 cycles the folder automatically. |
wall_rotation_interval |
300 |
Seconds between automatic changes. |
wall_nsfw_blur |
0 |
Blur cards that are marked NSFW until you point at one. |
Wallpaper viewer
Category: Aesthetics Importance: 4/5 Uniqueness: 4/5
Open one card full-screen to actually look at it. The image fits the screen rather than being stretched to it, you can pan and zoom into the pixels, and arrow keys walk the same list you were browsing so you never lose your place. Videos play in place, so a wallpaper can be a moving picture, and the viewer plays it with sound.
Why it is built in. A separate image viewer would be a second window with a second set of gestures. Here the viewer is the same surface as the deck: the card you clicked grows into the picture, and closing it shrinks back to the card you came from.
Online wallpaper sources
Category: Extension Importance: 4/5 Uniqueness: 4/5
The deck browses Wallhaven, Konachan, Yandere, Gelbooru and Pinterest directly, alongside your own folders. Search a site, scroll the results, save what you want. The card already carries the site's rating, its tags and the artist. When you save the file, all of that goes into your library with it, so a downloaded wallpaper arrives tagged.
How it works. Requests go out on a worker thread and never block the render path. Each source declares what it needs (a key, or nothing) and the deck says so plainly: an unbound source shows what keyless means for that site rather than presenting a control that does nothing. Anonymous access is used where a site allows it, and a source that rejects anonymous requests says so instead of appearing broken.
The colour driver (LookFX)
Category: Aesthetics Importance: 5/5 Uniqueness: 5/5
Your wallpaper decides what colour the rest of the desktop is. Borders, window glow, shadows, the bar, the notification centre, the music layer and the cursor all take the palette of the picture you are looking at. And they change colour over time rather than snapping.
How it works. The palette is pulled from the wallpaper as it is decoded, on a worker thread, and mixed in a colour space built the way people actually see colour. That is why pink to cyan does not pass through grey on its way there. The compositor holds the live colour and the timing; the shell asks it what the colour is right now rather than keeping its own copy, so nothing can disagree about what the desktop is wearing.
Each change picks one effect from a pool you choose:
| Effect | What it does |
|---|---|
fade |
A smooth crossfade that passes through colours you would expect. The default. |
sweep |
A wipe that travels across the desktop: left-right, top-bottom or diagonal, with a soft or hard edge. |
blurin / blurout |
The chrome softens as the old colour leaves, then sharpens as the new one lands. |
pop |
Overshoots the target colour and settles, and the glow and border pulse as it lands. |
hue |
Travels through hue instead of through RGB. |
pixel |
The colour resolves out of blocks, and the window's border and glow break into blocks that swell and settle. |
materialize |
The colour comes up out of a desaturated version of itself. |
none |
Snap. No animation. |
Every effect acts on the shell's own chrome: borders, glow, shadow. None of them is a filter over the whole screen. A full-screen pass recolours every window and wallpaper you did not ask it to touch, which is not a theme change.
What you use it for. One wallpaper change re-skins the whole desktop at once, and the
change is visible as a transition rather than a jump. Turn on PER-MONITOR and each screen
follows its own wallpaper. Turn on LIVE AS DRAWN and a near-black wallpaper cannot give
you a near-black border, so colours are lifted along their own hue until they are visible.
| Key | Default | Meaning |
|---|---|---|
lookfx_enabled |
1 |
The whole feature. 0 means chrome uses your pinned colours exactly. |
lookfx_per_monitor |
1 |
Each output follows its own wallpaper. |
lookfx_effects |
511 |
Which effects a change is allowed to pick. Each effect is one number, and you add up the ones you want on. |
lookfx_ms |
3000 |
How long a change takes. Under about 3 seconds it is barely noticeable. |
lookfx_legible |
1 |
Lift driven colours to a readable brightness along their own hue. |
lookfx_sweep_axis / lookfx_sweep_width |
0 / 0.45 |
The sweep effect's direction and edge softness. |
Per-panel colour
Category: Aesthetics Importance: 3/5 Uniqueness: 4/5
Every panel inherits the global theme, and any one of them can override it: the bar, the notification centre, the control centre, the music card, the deck and the LookFX panel. The tokens you can override are accent, secondary, surface, error, text, fill, rim, corner radius, font and animation speed.
What you use it for. A bar that stays quiet while everything else is loud. A notification centre with a softer corner. A deck with its own accent so it reads as a separate tool. Nothing you do to one panel can leak into another.
Toolkit themes
Category: Extension Importance: 4/5 Uniqueness: 4/5
GTK2, GTK3, GTK4, Qt5, Qt6 and KDE get the same palette, written once at the end of a colour change rather than every frame.
How it works, and the rule it obeys. UWWM never edits a file it did not create. It keeps
the real file under ~/.config/uwwm/theme/, links the standard path to it, and records in a
manifest what that path held before, so uwwm-ctl color restore puts everything back exactly
as it was. If you had your own gtk.css, it is still there.
uwwm-ctl color
Category: Extension Importance: 4/5 Uniqueness: 4/5
The palette from the command line. Running uwwm-ctl color on its own prints the
help.
uwwm-ctl color show # every output's palette, plus the base16 block
uwwm-ctl color --live # what the compositor is ramping right now
uwwm-ctl color replace terminal # recolour this terminal, the pywal way
uwwm-ctl color replace all # every output gets its own palette
uwwm-ctl color replace all feed clip.mp4 DP-1
uwwm-ctl color export term.json --format json
uwwm-ctl color restore # undo every toolkit file UWWM took over
Every screen keeps its own scheme. Two terminals on two monitors with two wallpapers get two different palettes. UWWM asks the compositor which window is focused and reads that window's output, matching on its position rather than its title, because three terminals can share a title and no two share a position.
replace terminal writes the palette as escape sequences to the terminal the
command runs in. It writes to the controlling terminal rather than to standard
output, so a script capturing the output does not swallow the sequences, and it
never clears your screen.
replace all pushes each output's own stored palette to that output. --mon or
--outputs narrows it.
replace all feed is an offline wallpaper carousel. It copies an image, gif or
video, or a whole folder of them, into the folder that output already chooses from,
then applies it through the same verb the deck uses. The palette comes from the
real decoded picture, so this works with the deck closed. --recursive walks
subdirectories, --mode picks the fit.
Keeping a terminal coloured. tmux holds a palette per pane and re-emits it
whenever it redraws one, which lands after anything a shell startup line writes. So
the palette has to be re-asserted, not set once. color export - prints the
sequences for the screen you are on, and a precmd hook sends them to the terminal
before every prompt. Resolve which screen you are on at the first prompt, not at
shell startup: at startup the window is not mapped yet, so the compositor reports
whatever was focused before it, and every prompt then re-asserts the wrong screen.
Export formats are json (pywal-shaped), dircolors, sequences (raw escape
codes) and kitty. show, help and export work with no compositor running,
because they read the palette store the deck writes. Exporting to a file takes
the first output, since the toolkit themes are one value per session.
-q / --quiet anywhere on the line drops the confirmation lines. Errors and exit
codes are unaffected, so a quiet call is still a checkable one.
What you use it for. A terminal, a GTK or Qt theme and a desktop that all match the wallpaper, updated by one hook on every wallpaper change, with no separate colour scheme to maintain.
HDR fed to applications
Category: Aesthetics Importance: 4/5 Uniqueness: 4/5
UWWM reports what your panel can actually reach, so a game or video player is told the truth about your display instead of assuming a generic one. HDR content arrives as HDR rather than being flattened to SDR on the way in.
What you use it for. HDR games and video on a panel that supports it. The desktop's own brightness, contrast and saturation grading still applies, and it happens on the display hardware, so it covers directly-scanned-out games too, at no frame cost.
Keyboard move and resize
Category: Movement Importance: 4/5 Uniqueness: 3/5
Every arrow key names the edge it moves, not a direction. In a packed row of windows, resizing one does not fight the layout: the row re-fits around it, and the window keeps its lean.
What you use it for. Precise layout without a mouse. Grow the right edge, shrink the top edge, and the neighbours move instead of overlapping.
Control centre pages
Category: Extension Importance: 3/5 Uniqueness: 3/5
The control centre opens from the bar: the clock, the power button, the hub pill, the stats pill and the audio pill each open it on a relevant tab. The LOOK page is surfaces, palettes and the colour pipelines, with a live preview that shows the theme you are actually wearing. The PANELS page is the per-panel overrides above, one row per token, with a read-back of what that panel is wearing right now.
How it stays honest. Every control writes to config.conf and takes effect the moment it
is saved. The panel measures what a page actually draws and grows itself to fit, so adding a
row to a page cannot silently push the last card off the bottom edge.
Troubleshooting
The background is black with effects enabled.
A wallpaper daemon (awww, swww) has to be running. The background pipeline filters
whatever is already being drawn; it doesn't generate an image itself. Also check that
foreground layering is enabled for the background shader.
Audio-reactive effects aren't reacting.
Check cava is running (cava -p ~/.config/cava/config_uwwm &) and that /tmp/uwwm_audio
exists and is receiving data. If you route audio somewhere unusual, check PipeWire's default
sink or set source explicitly in that config. If the file is missing, start UWWM once and
it writes the config on launch.
Notifications don't appear.
Source /tmp/uwwm_dbus_env in your session so applications find the compositor's bus, then
test with notify-send "Test".
A game isn't getting the direct, compositor-free path. That's the display hardware deciding whether it can scan the window's buffer out, which depends on the buffer's size and format. Windowed and borderless content with visible borders won't qualify; true fullscreen usually will. This is a correctness check, not a failure. Committing a buffer the display rejects would show as a black screen instead.
The media card stopped advancing. After a restart or reload, D-Bus property signals can desync. Press Stop (not Pause) in the player, then Play, to re-register the track.
Something looks wrong after editing the config. Most settings apply live. A few that change GPU buffer sizes or quality levels need a restart to reallocate cleanly.
Roblox / Sober has odd mouse input. Let it run natively on Wayland:
flatpak override --user --nosocket=wayland org.vinegarhq.Sober
Philosophy
UWWM exists to stop telling you how to use your computer.
The modern desktop has settled into two failure modes. One kind is soft, heavy, and fragile. The other uses "minimal" as an excuse to remove things you need and dictate the one layout it permits. UWWM takes the opposite position: maximum freedom, nothing compulsory, no compromise on frame timing.
- No forced paradigms. Infinite freeform canvas, keyboard tiling, zone layouts, a hidden scratchpad workspace, or pixel-perfect placement by dragging a box. All available, none mandatory.
- No daemon tax. The clock, notifications, media card, coordinates, and the control interface are drawn by the compositor itself. You are not running a 300 MB runtime to see the time.
- No gatekeeping. Layer-shell bars, external notification servers, wallpaper daemons, and floating menus all work, because it's standard Wayland underneath.
- No hidden latency. Input is processed before drawing, fullscreen content reaches the display directly, and the compositor's cost is something you can measure.
Your desktop is yours. Make it do whatever the fuck you want.
Under the hood
This section is for people who want to change UWWM, not just use it. Everything here is true of the current tree.
Two halves: C and Lua
The compositor is C. The entire on-screen interface is Lua, drawn by the compositor's GPU: the bar, the notification centre, the control centre, the wallpaper deck, the session shade and the music layer.
The split matters because they reload differently:
- Lua reloads while you are logged in. Save a
.luafile and the shell re-parses it in place. Nothing closes, no window is disturbed. This is how you iterate on the interface. - C needs a restart. The compositor is the thing holding your windows.
The compositor exposes a fixed list of functions to Lua through one FFI namespace. That list is the only place the bridge exists, so a shell cannot call something the compositor does not offer. The shells guard every call anyway, because a shell file can be newer than the compositor binary sitting under it: a symbol that does not exist is resolved once, cached as missing, and the shell falls back to something honest rather than throwing inside its own draw path.
Hot and cold code
The C side is split into a hot module and a cold core. Code that runs every frame lives in the hot module so it can be replaced without restarting the compositor; code that runs once lives in the cold core. The boundary is real, not cosmetic: hot globals are declared with a macro that puts them in the right place, and a function that reaches across the boundary fails to link rather than misbehaving quietly.
Config: one file, read live, written carefully
~/.config/uwwm/config.conf is watched. Save it and the compositor re-reads it and applies
what changed, on the next frame, without a restart. That is why almost every setting in this
README says "takes effect immediately".
Keys are matched by name, so most sections are documentation. Four are not, and the
parser reads them only inside their own section: [monitor.*], [wallpaper.*],
[close_rule.*] and [keybinds]. Move a key out of one of those and it stops working
silently. This is worth knowing because the compositor also writes this file, when you
change a wallpaper or a control writes a setting, and a save that reorganises the file can
therefore break your keybindings or your per-monitor HDR settings without saying so.
Missing keys are added automatically from the shipped default table, and a key that is present but blank is refilled from that same table. A blank value is not the same as a missing one: it parses, quietly, into the most wrong answer available. An empty colour is transparent, not default.
Colour: the compositor owns it, the shell asks
The live colour of the desktop lives in exactly one place in C. Shell widgets do not keep their own copy of the palette; they ask the compositor what the colour is right now. That rule exists because two copies drift, and when they drift you get a desktop that flashes and then snaps back.
The palette is pushed, never pulled: the moment a wallpaper's palette lands, the compositor is told, and the ramp starts at that instant rather than whenever something remembers to ask. Palette extraction happens on a worker thread as the image is decoded, because averaging a 6000×4000 picture on the render path would blow the frame budget.
Colour mixing is done in Oklab, not RGB. Mixing pink to cyan in RGB passes through grey; in Oklab it passes through the colours you would expect.
Wallpapers: staged, not swapped
Each output has two wallpaper textures: what is on screen now, and the next one, already decoded and uploaded but not yet shown. A transition blends between them and then commits by swapping the two slots, which is why a transition costs one blend rather than a decode on the render path. Uploads reuse the existing allocation when the size matches, so a folder of same-sized wallpapers never reallocates a texture.
HDR happens on the display, not in the compositor
HDR is applied through the display hardware, the CRTC's gamma LUT and connector metadata, rather than as a shader pass over the composited frame. That is what keeps directly-scanned- out games fast: the grade is free, because the hardware applies it on the way out.
The trade-off is that the display has to actually accept the mode. UWWM probes each output by asking the driver to test the state, and if the panel will not take the transfer function you asked for, the compositor falls back to a plain grade rather than baking an HDR encode into an SDR scanout, which is what an over-contrasted desktop looks like.
Adding a setting
A config key has four homes, and all four have to agree:
- the struct field in
src/uwwm_config.c, - its default in the defaults block,
- the parser branch that reads it,
- the generated default text, so a fresh install and an upgrade both get it with its explanation.
That last one is what makes the file self-documenting, and it is also what the reconcile pass diffuses against when a key is missing or blank, so a key that skips it can never be restored.
Adding or changing a widget
Edit the shell file and save. It reloads. If you need the compositor to tell you something new, add the C function and add its prototype to the FFI namespace list; then call it from Lua through the guarded resolver, so an older compositor degrades instead of erroring.
Testing without a monitor
The debug image builds as uwwm-dbg / uwwm-debg.so. Shell files are checked with
make check-lua, which lints every Lua file in the tree. Shell modules can also be loaded
offline under LuaJIT with a stub library standing in for the compositor's FFI symbols, which
is how a menu's rows or a colour calculation get exercised without a display at all.
Videos
Click to play:
Pre-chording
Drag out a region first, then launch. The window arrives already the size and position you asked for:
Does VR really work?
Heh, I got you ~
License
UWWM is derived from dwl and inherits its licensing. See LICENSE, plus LICENSE.dwm,
LICENSE.sway, and LICENSE.tinywl for the terms of the code it builds on.



