Your Wallpaper Engine library, running natively on Wayland.
One small Rust renderer. No Wine, no second engine.
WallForge on niri: opening the library and switching wallpapers.
Same clip as video (mp4, 1080p60, 18 s)
WallForge is a GTK4 / libadwaita app and the renderer behind it. It plays the Wallpaper Engine wallpapers you already own on any Wayland desktop with layer-shell support, and it manages them: search, per-wallpaper settings, audio, rotation, palette sync.
# Arch / CachyOS: install the package, then run it
sudo tee /etc/pacman.d/wallforge.conf >/dev/null <<'EOF'
[wallforge]
SigLevel = Optional
Server = https://pgm1207.github.io/WallForge/arch/x86_64
EOF
grep -q wallforge.conf /etc/pacman.conf || echo 'Include = /etc/pacman.d/wallforge.conf' | sudo tee -a /etc/pacman.conf
sudo pacman -Sy wallforge && wallforgeEverywhere else, build from source: it takes about a minute of compiling. You need to own Wallpaper Engine on Steam for the Workshop library and its shared assets; WallForge never ships or redistributes its files.
Works on: niri (tested), KDE Plasma on KWin 6.8 (tested), GNOME Shell 51 via the bundled extension (tested, video
wallpapers). Hyprland, Sway, river, Wayfire and labwc should work through wlr-layer-shell but are not tested yet:
reports welcome. Wayland only.
Contents · Why · What it plays · Screenshots · Performance · Rotation · Features · Install · FAQ · Roadmap · Troubleshooting · Documentation
| One app, not a pile | Library, settings, Discover, share links and the renderer in a single GTK4 window. Nothing else to install or configure. |
| Light by design | One small Rust process per screen, speaking Wayland and GLES directly. A still scene is drawn once and then sleeps; a 4K video wallpaper costs about 1% of one CPU core. |
| Looks right by default | Auto fit fills the screen (ultrawide art is cropped) and keeps portrait art whole. No stretched wallpapers. |
| Brings your setup along | Imports your Wallpaper Engine config.json: per-wallpaper properties, volumes, frame rate limit, fullscreen rule. |
| Plays the hard ones | Multi-pass effects, layer render targets, particles, embedded video, text with glow/outline, audio-reactive visualisers. |
| Fits your desktop | Palette sync with Noctalia, matugen, wallust or pywal; per-monitor wallpapers; rotation; restore at login; battery saving. |
Every scene wallpaper in our test library (77 installed Workshop scenes) starts with nothing skipped, except one 3D scene, which WallForge detects and refuses instead of showing a black screen. The full matrix, including what is still approximate, is in docs/compatibility.md.
| Wallpaper type | Status |
|---|---|
| Video | Hardware decode (VAAPI, zero-copy DMA-BUF), audio, gapless loop, volume and mute. |
| Scene (2D) | Layers, multi-pass effects, render-target sampling, particles, embedded video, text layers, property edits. SceneScript is not executed. |
| Web | WebKit on the wallpaper layer, with the wallpaper's properties. |
| 3D scenes | Not supported; detected before you apply one. |
![]() |
![]() |
| Library: everything you subscribed to, with search, filters and favourites | Settings: setup status at a glance, then playback, rotation, power and desktop |
Recorded from the renderer: a Wallpaper Engine scene with a multi-pass fluid simulation, no post-processing.
Same clip as video (mp4, 5 s)
Measured on a Ryzen 9 9900X with a Radeon RX 9070 (RADV), 3840×2160 output, default 30 fps, one wallpaper.
tools/bench.sh <workshop-id> reproduces the whole table on your own machine, including the idle GPU baseline.
| Wallpaper | CPU (one core) | GPU | Process RSS | Scene textures |
|---|---|---|---|---|
| 4K video, hardware decoded | ~1% | ~5% (idle desktop is ~3%) | 135 MB | — |
| Static scene | ~0% | drawn once, then sleeps | 107 MB | 32 MB |
| Fluid-simulation scene (19 effect passes) | ~2% | ~14% | 124 MB | 142 MB |
Settings that trade a little sharpness for a lot less GPU time:
- Render resolution (%): scene wallpapers are drawn at 25–100% of the screen size and upscaled with linear filtering. Videos and web wallpapers always play at native resolution. 100% is the default; 75% is a good compromise on a laptop or a shared GPU, 50% makes a heavy scene comfortable on an integrated GPU.
- Frame rate limit: 30 fps by default (5–240). 24 is enough for most wallpapers and nearly halves the work of 60.
- Disable particles, Disable parallax, Disable mouse interaction: turn off the effects that cost the most and that you are least likely to notice under your windows.
- Reduce frame rate and resolution on battery: while discharging, the limit drops to 30 fps and the render scale to 75% at most, without touching your settings.
- Preload the next wallpaper: the next pick (rotation, Ctrl+Shift+N) is loaded behind the current one, so the switch is one frame (~30 ms) instead of a load. It costs that wallpaper's memory while it waits; turn it off if your GPU is short on memory.
- Pause wallpapers on battery: stops every wallpaper while discharging and brings them back when you plug in.
If a wallpaper stops on its own, WallForge restarts it; after three failures in five minutes it leaves the screen idle and says so in the playing bar instead of looping on a crash.
Settings > Playback > Change wallpaper every switches to a new wallpaper every N minutes (0 turns it off). Pick a random wallpaper chooses at random; with it off, the library order is followed. Rotate only through favourites keeps the rotation to wallpapers you starred. Give each screen its own wallpaper rotates each monitor independently, so two screens get two different wallpapers; with it off they all change to the same one. Rotation waits while wallpapers are paused by battery saving, never picks a wallpaper that is already showing, and leaves screens you stopped by hand stopped. Ctrl+Shift+N switches now without waiting for the timer.
While rotation is on, closing the window keeps WallForge running in the background so the timer keeps working; open it again from the menu (or your launcher) and it comes straight back. Ctrl+Q quits for good.
- Library of everything you subscribed to, with search, type filter, sort, favourites and a random button.
- Every property type is editable per wallpaper (sliders, colours, combos, text, image slots) and applies live.
- Volume per wallpaper, on top of the global volume and mute.
- Discover tab browses the Steam Workshop, with one-click Get through your running Steam client (experimental: if the click fails, Steam opens the page for you).
- Share and open links: copy any wallpaper's Workshop link, or paste one into Discover.
- Import from Wallpaper Engine: your customised wallpaper settings, volumes and playback rules.
- Per monitor: apply to one screen or all. Ultrawide wallpapers are cropped to fill 16:9 screens, or skipped if you prefer.
- Auto scaling by default; fill, fit and stretch are in Settings.
- Palette sync with Noctalia, matugen, wallust, pywal or a custom command.
- Restore at login: a tiny background daemon (
wallforge --daemon) sets your wallpapers at login, restarts them if they crash, follows monitor changes and keeps them above other wallpaper clients (toggle in Settings, on by default). - Audio-reactive wallpapers hear what you play: visualisers and spectrum effects are driven by the system's audio output, with no microphone involved, and stay idle when no wallpaper asks for them.
- Safe: a crash shows a toast with a "View log" button, a dead renderer is restarted automatically, broken files are caught by a watchdog, and unsupported 3D scenes are detected before you apply them.
- Sensible defaults: anime and mature content are hidden until you switch them on in Settings.
Keyboard: Ctrl+F search · Ctrl+R random wallpaper · Ctrl+Shift+N rotate now · Ctrl+, settings · F5 rescan ·
Esc hide the sidebar · Ctrl+Q quit (including from the background).
-
A Wayland desktop. X11 is not supported.
Desktop How it draws Tested niri, Hyprland, Sway, river, Wayfire, labwc wlr-layer-shellniri KDE Plasma (Wayland) wlr-layer-shell(KWin has implemented it since Plasma 5.20)KWin 6.8 GNOME 51 the bundled GNOME Shell extension (Settings > Setup > Install GNOME extension, or install.sh; log out and in once)GNOME Shell 51, video wallpapers, headless On GNOME, web wallpapers are not supported yet (the web player needs layer-shell), and the extension's
metadata.jsonlists only GNOME Shell 51, the one version it was tested on (older and newer versions are untested).make zip(tools/gnome-ext-zip.sh) builds the extensions.gnome.org upload zip withgnome-extensions pack. -
Python 3.11+, GTK 4, libadwaita 1.5+, PyGObject, Pillow, aiohttp, ffmpeg. For the renderer: Rust, clang, libva and EGL. For web wallpapers:
webkitgtk-6.0andgtk4-layer-shell. -
Steam, signed in to an account that owns Wallpaper Engine, to download Workshop wallpapers. Scene wallpapers also need Wallpaper Engine's shared
assets/folder, which WallForge never ships — here is how to get it.
Run wallforge --doctor at any time (or ./wallforge.sh --doctor from a source checkout) to check all of the above
on your machine and print what to fix.
Every release is packaged and published to a pacman repository, so Arch and CachyOS install and update it with pacman:
sudo tee /etc/pacman.d/wallforge.conf >/dev/null <<'EOF'
[wallforge]
SigLevel = Optional
Server = https://pgm1207.github.io/WallForge/arch/x86_64
EOF
grep -q wallforge.conf /etc/pacman.conf || echo 'Include = /etc/pacman.d/wallforge.conf' | sudo tee -a /etc/pacman.conf
sudo pacman -Sy wallforgeThose packages are unsigned and the repository sets SigLevel = Optional; if you sign your own repositories, build
from source instead. What is published, and how it is built, is in packaging/arch-repo/.
A wallforge-git PKGBUILD is in packaging/aur/. It is not on the AUR yet (the AUR pauses new
registrations from time to time); build it with makepkg -si from that folder in the meantime.
# Arch / CachyOS
sudo pacman -S python-gobject gtk4 libadwaita python-pillow python-aiohttp ffmpeg libva rust clang \
webkitgtk-6.0 gtk4-layer-shell
git clone https://github.com/pgm1207/WallForge
cd WallForge
./install.sh # builds the renderer (about a minute), adds a menu entry and icon
./wallforge.shinstall.sh installs into ~/.local/opt/wallforge, adds a wallforge command, the menu entry and the login
service, and builds the renderer. The checkout stays the source of truth, so updates keep working.
One line, from anywhere; it updates the installed copy, rebuilds the renderer and restarts a running session:
curl -fsSL https://raw.githubusercontent.com/pgm1207/WallForge/main/update.sh | bashOr, from a checkout you keep:
git pull && ./install.sh --from-gitinstall.sh --no-build skips the renderer build and keeps the installed binary.
On other distributions, install the same pieces from your package manager:
| Distribution | Packages |
|---|---|
| Fedora | python3-gobject gtk4 libadwaita python3-pillow python3-aiohttp ffmpeg-free rust cargo clang libva-devel mesa-libEGL webkitgtk6.0 gtk4-layer-shell |
| Debian 13+ / recent Ubuntu | python3-gi gir1.2-gtk-4.0 gir1.2-adw-1 python3-pil python3-aiohttp ffmpeg cargo clang libva-dev libegl1, plus libgtk4-layer-shell0 gir1.2-gtk4layershell-1.0 for web wallpapers |
Names drift between releases and only the Arch list is exercised in CI, so run wallforge --doctor afterwards: it
names whichever piece is missing instead of making you guess.
Select a wallpaper and press the share button in its panel (next to the favourite star). The link to its Steam Workshop page is copied to the clipboard, and the toast offers to open the page. Discover cards have the same button.
To open a link someone sent you, paste it into the Discover search box and press Enter. If you already have the wallpaper it opens in your library; otherwise its card appears with a Get button. A bare Workshop id works too.
Only wallpapers that are on the Workshop have a link. The button is greyed out for local projects.
Settings > Wallpaper Engine > Import settings reads the config.json that Wallpaper Engine keeps in its install
folder (steamapps/common/wallpaper_engine/config.json). If you used Wallpaper Engine on Windows, pick the file from
your Windows drive with Choose file. You see what would change before anything is written.
| Imported | Not imported |
|---|---|
| Each wallpaper's customised properties (colours, sliders, switches, combos, text) | Playlists |
| Each wallpaper's volume | Per-wallpaper alignment, playback speed and colour adjustments |
| Frame rate limit | Image and file properties (they point at Windows paths) |
| The fullscreen pause rule | Settings of wallpapers that are not installed here |
| Optionally, the wallpaper that was active |
From a terminal: wallforge --import-we [path/to/config.json] [--dry-run].
Details are in docs/wallpaper-engine-import.md.
You do not need Wallpaper Engine installed, but you do need to own it. Scene wallpapers need its assets/ folder
(shaders and textures), which WallForge never ships. Video and web wallpapers do not need it. Use either:
- Fetch from Steam (about 85 MB). Settings > Setup > Fetch assets from Steam opens a terminal where you sign in to Steam with DepotDownloader (pinned release, checksum verified). Your password goes to DepotDownloader only, never to WallForge. An account that does not own Wallpaper Engine is refused by Steam.
- Install it in Steam (about 0.8 GB). WallForge uses its
assets/folder directly.
Workshop wallpapers themselves are downloaded by the Steam client when you subscribe.
Wallpapers do not have to come from the Workshop. Click + in the header (or run wallforge --import PATH) and pick:
- Video or GIF (mp4, webm, mkv, mov, gif): the file is linked, not copied, so big videos use no extra disk. If you move or delete the original, the item shows as broken; use
--copyto keep a copy instead. - Image: shown as a full-screen page.
- HTML folder (or an
index.html): copied in as a web wallpaper. - Lively
.zip: video, GIF, web and picture packages work. Lively app, Unity, Godot, URL and BizHawk wallpapers are refused with a message.
Items live in ~/.local/share/wallforge/library/local-*/ with a normal project.json, show up in the grid, and can be uninstalled from their detail panel. Every card carries a source badge (Wallpaper Engine, Lively, Local, Wikimedia) and the Library has a source filter. A preview is made with ffmpeg when it is installed. Only add packages you trust: web wallpapers run as web pages.
Discover has a source selector: Wallpaper Engine Workshop or Wikimedia Commons. Commons offers free videos
(landscape, 720p or more) from categories such as nature, time-lapse, clouds, waterfalls and cities. No account or key
is needed. Only files under public domain, CC0, CC BY and CC BY-SA licences are listed. The card and the detail page show
the licence and the author, and Download copies the 1080p WebM into your library with the licence, author and a ready
attribution line (CC BY / BY-SA ask you to credit the author if you share or show it). Search from a terminal with
wallforge --commons [QUERY] [--topic Waterfalls] [--get N]. WallForge identifies itself with a generic User-Agent,
asks for small pages and honours the API's maxlag.
Uninstall in the library detail panel (and the trash button on installed Discover cards) asks first, stops the wallpaper if it is playing, then removes it. Items you added or downloaded from Commons are deleted (a linked video's original file is kept). Workshop wallpapers are managed by Steam, so deleting the folder would only make Steam download it again: WallForge opens the item's Workshop page and you click Unsubscribe there.
wallforge is the command from a package install; from a checkout it is ./wallforge.sh. Both take the same flags.
| Command | What it does |
|---|---|
wallforge |
The app. |
wallforge --daemon |
Session supervisor started at login (systemd user unit, XDG autostart, niri spawn-at-startup); single instance. |
wallforge --restore |
Re-apply the saved wallpapers once and exit. |
wallforge --doctor |
Check the setup (Wayland, layer-shell, GTK, assets, renderer, decode) and exit; read-only, no display needed, exit code 1 when something is broken. |
wallforge --import-we [FILE] [--dry-run] |
Import Wallpaper Engine's settings. |
wallforge --commons [QUERY] [--topic NAME] [--get N] |
Search Wikimedia Commons videos; --get N imports result N. |
wallforge --import PATH... [--copy] |
Add a video, image, HTML folder or Lively .zip to the library (see Other sources). |
The renderer and the web player can also be run on their own; see render/README.md for
wallforge-render --check, --scale, --no-audio-processing and the rest.
WallForge checks GitHub at start and every few hours (switch it off in Settings > Updates). A git clone updates
itself: it pulls the new version in the background (git pull --ff-only), checks that it loads, rolls back if it
does not, then offers "Restart now". Local edits in the folder are never overwritten. A package install only tells
you and leaves the update to your package manager.
Do I need Wallpaper Engine installed? Installed, no; owned, yes, for scene and web wallpapers. WallForge reads the
shared assets/ folder from your own copy, or fetches it from Steam with your account. Video wallpapers need nothing
but the file.
Is this a wrapper around linux-wallpaperengine or Wine? Neither. wallforge-render is a Rust renderer that reads
the wallpaper's project.json, scene.json and its shaders, and draws them with GLES on a layer-shell surface. See
docs/comparison.md for how it compares, including where the other projects do better.
Will it work on GNOME or KDE? KDE Plasma: yes, KWin has implemented wlr-layer-shell since Plasma 5.20 (tested on
KWin 6.8). GNOME 45+: yes, through the bundled shell extension, because GNOME has no layer-shell (tested on GNOME Shell
51 with video wallpapers; web wallpapers do not work there yet). See the table above.
Why is SceneScript not supported? Scenes that ship a script (scripted camera moves, media panels, sequences) run only part of their logic here; the picture still appears, but it can be incomplete. It is the largest remaining gap and it is listed in docs/compatibility.md.
Can each monitor show a different wallpaper? Yes. Pick a wallpaper, choose the screen in the play controls, or use Give each screen its own wallpaper in rotation so they change independently.
Ultrawide wallpaper on a 16:9 screen? It is cropped to fill, never stretched. Switch Allow ultrawide wallpapers on 16:9 screens off in Settings to skip them instead. On a 16:9 wallpaper on an ultrawide screen, fill crops, fit letterboxes.
How much does it cost while I work? About 1% of one core for a 4K video, and a still scene sleeps after its first
frame. The performance table is measured, not estimated, and tools/bench.sh reproduces it.
Does it come back after a reboot? Yes: Restore at login (on by default) starts wallforge --daemon through a
systemd user unit, XDG autostart and niri's startup list. On Hyprland or sway without systemd, add exec-once = wallforge --daemon (Hyprland) or exec wallforge --daemon (sway) to your config; wallforge --doctor shows what is set up.
Scene wallpapers are the hard part, and some still render differently from Wallpaper Engine. Please open an issue with the wallpaper's Workshop link (the share button copies it) and its log — Settings > Updates > Copy diagnostics puts the version, GPU, the renderer's report for that wallpaper and the last log lines on the clipboard in one click.
Logs live at $XDG_RUNTIME_DIR/wallforge/<output>.log, and the crash toast has a View log button.
wallforge --doctor checks the setup itself, and docs/troubleshooting.md covers the common
problems.
What is next, roughly in order. Each item has an issue; a thumbs-up there is how priorities get decided.
- Sound layers: 25 of the 77 scenes in our test library carry sound objects that are silent today.
- SceneScript: run the scripts scenes use for clocks, media panels and scripted camera moves.
- Puppet (mesh) animation for character scenes.
- Bloom and HDR post-processing matching Wallpaper Engine's look.
- More packages: AUR (waiting on AUR registration), Flatpak, Fedora COPR.
Smaller tasks that fit a first contribution are labelled good first issue. No dates are promised. Contributions are welcome, from a Workshop link that renders wrong to a renderer fix; CONTRIBUTING.md shows how to build, test and where to start.
- docs/comparison.md: WallForge next to other ways of playing Wallpaper Engine content
- docs/compatibility.md: which Wallpaper Engine features are supported
- docs/wallpaper-engine-import.md: exactly what the import reads
- docs/troubleshooting.md: setup problems, logs, known limits
- render/README.md: the renderer, its flags and internals
- CONTRIBUTING.md: building, testing against your library, sending fixes
- SECURITY.md: reporting a vulnerability
- CHANGELOG.md
Not affiliated with Wallpaper Engine, the Wallpaper Engine Team or Valve. No Wallpaper Engine files are included or redistributed; they come from your own Steam account. MIT licensed.




