Waywallen, a dynamic wallpaper daemon for Linux with a plugin layer

From a KDE plugin to a standalone daemon

Waywallen is a dynamic wallpaper solution for Linux desktops, and it started life as a Wallpaper Engine plugin for KDE. That origin explains the design, because a Wallpaper Engine plugin runs inside Wallpaper Engine, and taking that model to a Linux desktop meant taking the model apart and rebuilding it as a daemon with a display process behind it.

The result is a two-part system, and the README makes that explicit in the desktop integration table. The application is the daemon, and the wallpaper is actually drawn by a separate helper called waywallen-display, which is a separate repository. For the compositors that use layer-shell, the relevant binary is a different one, layer_shell, taken from the same repository at src/bin/layer_shell.

The table of supported desktops is the most useful part of the README, and the differences in it are informative. KDE Plasma and GNOME both use the waywallen-display integration and both have mouse input and auto pause. Hyprland, Niri, Wayfire, COSMIC and Sway use the layer_shell path, and all of them have mouse input. Sway is the exception on auto pause, which is marked as unsupported.

That last row is a useful detail. Auto pause is presumably the behaviour of stopping the wallpaper when something is on screen, and the fact that Sway does not have it while every other compositor does suggests it depends on compositor-specific features rather than on the daemon.

The project is written in Rust, with the Cargo.toml showing a workspace with a second member, tools/wayproto-gen, and the main package at version 0.4.4. The release tags are v0.4.4 from 2026-10-06, v0.4.3 from 2026-09-26 and v0.4.2 from 2026-09-25, so the project is moving quickly, with several releases in the last few weeks. The last push was on 2026-10-13, the default branch is main, and the licence is MIT.

The user interface is in the ui/ directory and the screenshot in the README is of the main page, which is the configuration surface for a wallpaper manager rather than anything more ambitious.

Plugins, and what running one actually means

The wallpaper plugins are listed in three groups. There is an image plugin and a video plugin, with hardware decoding via Vulkan and VA-API for the video one, and a Wallhaven plugin.

The third-party section is where the project is most careful, and the warning is worth reading in full. Third-party plugins are trusted code. A plugin's Lua entry point runs inside the Waywallen daemon with your user account's privileges, just like any application you choose to install, so it can read and write your files and access the network. The instruction is to only install plugins you trust, preferably after reviewing their source.

That is a real constraint and worth understanding before you add anything. The Lua runtime is mlua, with the features lua54, vendored, send, async and serialize, which means a plugin can be asynchronous, can send messages, and can be serialised. In other words a plugin is not a limited scripting sandbox, it is an embedding of a full scripting language with the daemon's own privileges, and the security model is the same as installing an application.

The one third-party plugin listed is open-wallpaper-engine, a separate repository that adds scene support and web support. Installing a third-party plugin is a manual step, the README says to download its ZIP archive and install it from the plugins page in the UI, and after installation Waywallen will notify you of plugin updates and install them.

The auto-update behaviour is notable. The plugin update path is handled for you, which means a plugin author can push a fix and have it reach installed copies without the user doing anything, and it also means the trust decision is being made once and then applied repeatedly.

The repository layout reflects the split: a plugins/ directory for the plugin implementations, a protocol/ and proto/ directory for the wire protocol between the daemon and the display process, a bridge/ directory, a src/ directory for the main crate, the ui/ directory, and a tools/ directory for the code generator.

Video decoding, and the decision not to write an NVDEC backend

The FAQ explains how hardware video decoding works, and the answer is a fallback chain. The default auto mode uses the order vulkan, then vaapi, then sw, meaning software decoding as the last resort. You can select the hwdec mode in the waywallen-video settings instead of using auto.

Then comes the decision that says the most about the project. There is no plan to add a dedicated NVDEC backend. NVIDIA users should use nvidia-vaapi-driver to expose NVDEC through VA-API.

That is a deliberate refusal to implement the vendor-specific path, and the reasoning is visible in the alternative. Writing a native NVDEC backend means binding to a proprietary API that changes between driver generations, and it would work on one vendor's hardware only. Going through VA-API means one code path serves every vendor, and the driver does the vendor-specific part, at the cost of one extra layer. For a project that has to work on seven compositors and an unknown number of GPU vendors, the single path is the maintainable choice.

The dependency list supports this reading. There is ash for raw Vulkan control, with the comment in the Cargo.toml explaining it is for the waywallen-renderer subprocess and specifically for raw Vulkan control over DMA-BUF export and semaphore sync_fd export. So the Vulkan path is handled at a low level, which is what makes the vulkan-first fallback order possible, and it needs an ash binding to do it.

The rest of the stack is a coherent set of choices for a daemon that talks to a desktop session. tokio with the full feature set, zbus for D-Bus, ashpd for the XDG desktop portal, and reqwest with rustls-tls, http2 and streaming for network access, which is what the Wallhaven plugin needs. nix with fs, ioctl, socket and uio for the low level system work, sea-orm for the database layer, and mlua for the plugin runtime.

Known issues, logging and debugging

The Known issue section is short and specific, which is a good sign for a project with a wide hardware and compositor range.

A recent NVIDIA driver has a bug with egl, and the workaround is to set QSG_RHI_BACKEND=vulkan when running plasmashell, with more details at the waywallen-display repository. Web wallpapers on NVIDIA GPUs require shared_texture_enabled to be disabled in the web renderer settings.

Flatpak needs one extra permission, and the README gives the command:

flatpak override --user --talk-name='org.mpris.MediaPlayer2.*' org.waywallen.waywallen

That is the MPRIS permission, needed to read information about the currently playing track, which is what lets the wallpaper react to music.

Logging is documented in detail, which matters for a background daemon. Daily daemon logs are written under ~/.local/state/waywallen/logs/daemon/ or the equivalent under $XDG_STATE_HOME, named waywallen.YYYY-MM-DD.log with up to 8 kept, and waywallen-current.log points at the active file. To raise verbosity you stop the running daemon and restart it with WW_LOG=debug, and for Flatpak the logs are under ~/.var/app/org.waywallen.waywallen/.local/state/waywallen/logs/daemon/.

The Flatpak debugging section is the most detailed answer in the FAQ and shows the level of support offered. You install the debug variant with flatpak install org.waywallen.waywallen.Debug and run it with --devel --command=bash, then attach gdb to the process, answer no to the debuginfod prompt, and get a stack trace with bt. The alternative is a core dump, taken with coredumpctl dump and then opened in gdb. The Flatpak README translations are in Chinese and Russian, and the project also ships a LOGGING.md file in the repository root.

Editorial conclusion

Waywallen suits someone on a Linux desktop who wants Wallpaper Engine style dynamic or video wallpapers without leaving Linux, particularly on Wayland compositors where the traditional wallpaper setters do not work. It is the wrong choice if you need the full Wallpaper Engine feature set, because the third-party open-wallpaper-engine plugin adds scene and web support but the core project is image and video, and it is the wrong choice if you will not install third-party plugins, because a plugin runs as your own user account inside the daemon. Before installing, read the warning about third-party plugins, and on Flatpak grant the MPRIS D-Bus permission the README asks for.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. waywallen/waywallen on GitHub