Most Wayland setups are held together with duct tape. You end up installing five or six separate tools (swww or awww, mpvpaper, linux-wallpaperengine, glpaper, wpaperd, plus matugen or pywal) just to get wallpapers, video loops, Steam Workshop scenes, music bars, and matching system colors.
WayWal replaces the whole pile with tiny C23 binaries (2.91 MiB total stripped). Drop in a photo, a 4K video, a live shader, or a Steam Wallpaper Engine scene, and your whole desktop updates its color theme in half a millisecond. And the instant a window covers your screen, WayWal drops to 0.0% CPU and GPU so your battery stays untouched.
- One command for everything (
wwal img): Pointwwal imgat a picture, a GIF, a 4K video, a Shadertoy file, a Steam Workshop ID, or a folder. WayWal detects the format on its own. Then it blends the new wallpaper onto your screen at your monitor's full refresh rate. - Native Steam Wallpaper Engine: Run your Steam Workshop scenes straight on Wayland. Puppet meshes with 240 Hz spring-bone physics and 3D curl-noise wind, 3D perspective cameras and dynamic multi-light rigs, 50 built-in stock effects with automatic HLSL-to-GLSL translation, particles, scripts, clocks, and sound layers all work natively. No Wine, no Proton, and no heavy wrapper.
- Whole-desktop colors in
0.5 ms: Change your wallpaper and your whole system shifts colors to match in half a millisecond. WayWal builds dark and light palettes at once and updates your terminal, bar, browser, and lockscreen right away. Existingmatugen,wallust, andpywaltemplates work as-is. - Built-in shaders, visual node graph & audio visualizers: Ships with 10 procedural GPU shader presets, 50 stock post-processing and distortion effects, live PipeWire audio bars and rings that move to your music, and a visual
.wwgraphnode-graph shader compiler. - Sun-tracked day and night wallpapers: Give it your location (or a GNOME timed wallpaper) and your desktop shifts from dawn to noon to night with the real sun, flipping your apps between light and dark mode along the way.
- Zero wasted battery (
0.0%when covered): Still images use0.0%CPU and0.0%GPU once drawn. Videos use hardware VA-API decoding (~0.3%CPU). Open a window full screen or launch a game, and WayWal pauses right away. It mutes background sound too, then wakes back up when you can see your desktop again. - Drop-in replacement for
swww,awww, andwpaperd: Keep your old scripts and keybinds. WayWal readsswwwandawwwCLI flags directly, loadswpaperdconfigs, and includeswwal pickso you can browse thumbnails inrofi,fuzzel, orwalkerin under1 ms. - WayWal Studio GUI (
wwal-studio): Includes an optional Wayland GUI workstation across 7 workspace perspectives (Default,Shader Coding,Scene Composer,Particle & Audio,Rigging & Animation,Theme Studio,Multi-Monitor) and 22 dockable panels to browse local wallpapers, Steam Workshop (431960), and WayWal Open Hub packages; compose WYSIWYG layers withSceneLayerTreeWidgetand interactive viewport gizmos; paint GPU masks, flow maps, blur, and smudge viawe_gpu_brush; generate 2D puppet meshes via Constrained Delaunay Triangulation (we_mesh_cdt), bind bones with harmonic heat-diffusion skinning and a GLES 3.1 GPU weight brush, pose 2-bone IK & Aim constraints, and keyframe animations inDopeSheetTimelineWidgetwithstudio_rig_<id>.jsonsidecars; author particle emitters and PipeWire audio bindings; edit GLSL ES 3.10 and SceneScript with livewe_script_lintdiagnostics; compose multi-pass shaders in a visual node graph editor with 50 drag-and-drop effects; tune 3D cameras, lights, and spring-bone physics; preview Material You color themes; arrange multi-monitor spans; and exportMDLV0023puppets,PKGV0022/TEXV0005scenes, or Ed25519-signed.wwpkgpackages.
WayWal is written in C23 and talks directly to Wayland, DRM/KMS, and your GPU:
- Binary size:
2.50 MiB(2,623,592 B) daemon (wwald) +414 KiB(424,000 B) client (wwal),2.91 MiBtotal stripped. - Still pictures:
0.00%CPU and0.00%GPU once the frame is on screen. - Covered by a window:
0.00%CPU,0.00%GPU, and0wakeups/sec. - 4K video loops:
~0.3%CPU via hardware VA-API decoding. - Theme extraction + template render:
0.49 msend-to-end (0.44 mspalette +0.05 mstemplates). - Wallpaper picker (
wwal pick):0.93 mswarm cache (61.2 msfirst-run thumbnail build). - Lockscreen frame export (
1280×720):13.0 msready forhyprlockorswaylock. - 4K GPU transitions:
1,668 – 2,734 FPSat3840×2160.
See Technical Architecture & Full CLI Reference for the full benchmark suite and internals.
# Prebuilt binary (fast install)
yay -S wwal-bin
# Or build latest from source
yay -S wwal-gitsudo dnf copr enable execorn/wwal
sudo dnf install wwalsudo zypper addrepo https://download.copr.fedorainfracloud.org/results/execorn/wwal/opensuse-tumbleweed-\$basearch/ execorn-wwal
sudo zypper --gpg-auto-import-keys refresh
sudo zypper install wwalcurl -LO https://github.com/Execorn/wwal/releases/latest/download/wwal_3.0.0_amd64.deb
sudo apt install ./wwal_3.0.0_amd64.debnix profile install github:Execorn/wwal- Install your system build tools (
meson,ninja,gccorclang,pkg-config) and base libraries (wayland,wayland-protocols,libdrm,mesa,libva,liburing,libseccomp,libpng,libjpeg-turbo, plus optionalqt6-baseandsqlite3forwwal-studio). - Build and install (pass
-Dstudio=disabledfor a headless/CLI-only build):
git clone https://github.com/Execorn/wwal.git
cd wwal
meson setup build --prefix="$HOME/.local" --buildtype=release -Doptimization=3 -Db_lto=true -Dstudio=auto
meson compile -C build
meson install -C buildStart the background daemon once (or add wwald & / swww-daemon & to your compositor startup file):
wwald &# Set a wallpaper with a ripple effect starting at your mouse cursor
wwal img ~/Pictures/Wallpapers/mountain.jpg --transition-type ripple --transition-pos cursor
# Frame portrait art from the top and pick the secondary accent color (0..3)
wwal img ~/Pictures/Wallpapers/portrait.png --crop-gravity top --theme --source-color-index 1
# Pass a photo, video, shader, Workshop ID, GNOME .xml, or folder to `wwal img`
wwal img 2841902341# Open Rofi / Fuzzel / Walker with thumbnails for images, videos, shaders & Workshop items
wwal pick
# Output JSON metadata + thumbnail paths for Quickshell / Eww / AGS widgets
wwal pick --menu json
# Launch the WayWal Studio GUI (library browser, shader/scene sliders, theme studio & monitor canvas)
wwal-studio
# Launch Studio scanning specific wallpaper folders while excluding subfolders
wwal-studio -d ~/Pictures/Wallpapers -x Screenshots# Play a looping 4K video wallpaper
wwal video ~/Videos/rain.mp4
# Play a video at 40% volume, and auto-duck it when other apps play sound
wwal video ~/Videos/scenic.mp4 --volume 0.4 --mute-on-audioIf you own Wallpaper Engine on Steam, wwal finds and runs your Workshop library natively:
# List your installed Steam Workshop wallpapers
wwal workshop list
# Apply a Workshop wallpaper by its ID or folder path
wwal workshop apply 2841902341
# Create preview symlinks (~/.cache/wwal/workshop-previews/) for GUI pickers like Waypaper
wwal workshop sync-previews# List all 10 built-in shaders and launch one with live PipeWire audio reactivity
wwal shader list
wwal shader preset audio_bars --audio
# Run a mixed-media slideshow and step forward or backward
wwal slideshow ~/Pictures/Wallpapers --interval 30m --sort mtime
wwal next
wwal prevwwal restore # Restore your last wallpaper on login
wwal pause # Pause active video, shader, or Workshop animation
wwal toggle # Toggle pause and play
wwal clear 1e1e2e # Set a zero-RAM solid color background
wwal status # Show current wallpaper, screen info, and active colorsWayWal works out of the box with no setup. If you want to save default transitions, app color templates, battery rules, or sun schedules, copy the example file to ~/.config/wwal/config.toml:
mkdir -p ~/.config/wwal
cp contrib/config.toml.example ~/.config/wwal/config.toml- Annotated Example Config (
contrib/config.toml.example): Ready-to-copyconfig.tomlwith comments for every setting. - Configuration Manual (
docs/man/wwal-config.5.scd): Full guide for all TOML sections, template variables, pipe filters, and sun schedules (also available viaman 5 wwal-config).
- Technical Architecture & Full CLI Reference: Wayland protocols, GPU shaders, video decoding, Workshop runtime, and all CLI flags.
- Support & Troubleshooting: Quick fixes for common setup questions.
- Contributing: How to build, run tests, and send changes.