Wallr

GPU-accelerated wallpaper engine for Wayland, rendered natively with wgpu on wlr-layer-shell.

Wallr renders its own background surface on wlr-layer-shell compositors. It does not shell out to hyprpaper, swaybg, or swww.

Features

• Static, GIF, and video wallpapers (MP4, WebM, MKV) with hardware-accelerated decode
• 11 transitions — fade, blur, wipe, slide, zoom, pixelate, ripple, dissolve, wave, grow, outer
• Per-monitor wallpapers and scaling modes
• Background daemon over a Unix socket, with directory watching for auto-apply
• Optional post-apply theming via Matugen, Wallust, or Pywal
• YAML animation packages with an install/search registry
• Near-zero idle overhead: static wallpapers render once and sleep; video and GIFs pace to frame boundaries

Screenshots

 
Catppuccin Mocha sunset — audio visualizer and fetch widget (left), system monitor and git workflow (right)

Install

cargo install wallr

yay -S wallr-bin

nix run github:programmersd21/wallr

Usage

wallr set wallpaper.jpg
wallr set wallpaper.jpg --effect grow --origin bottom_right --duration 1.2s
wallr set video.mp4 --effect wave --duration 1s
wallr watch ~/Pictures

wallr set starts the daemon automatically if it isn't already running. Full flag reference: docs/cli-reference.md.

Configuration

~/.config/wallr/config.yaml:

wallpaper:
  default: "~/Pictures/Wallpapers/default.png"
  mode: "fill"

animation:
  use: "smooth/crossfade"
  duration: "2000ms"

theme:
  provider: "matugen"

reload:
  - "waybar"
  - "dunst"

Full schema: docs/config-reference.md.

Requirements

Compositor	Hyprland, Sway, niri (layer rule required), or KDE Plasma 6 — any wlr-layer-shell implementation. GNOME/Mutter is unsupported.
Rust	stable, for building from source
FFmpeg	required only when building from source, for video wallpapers. Prebuilt release binaries statically link FFmpeg.

Building from source

# Arch
sudo pacman -S rust wayland wayland-protocols pkg-config ffmpeg

# Fedora
sudo dnf install rust cargo wayland-devel wayland-protocols-devel pkg-config ffmpeg-devel

# Ubuntu/Debian
sudo apt install rustc cargo libwayland-dev wayland-protocols pkg-config libavcodec-dev libavformat-dev libavutil-dev libswscale-dev

git clone https://github.com/programmersd21/wallr.git
cd wallr
cargo install --path wallr

Architecture

The wallr CLI talks to wallr daemon over a Unix socket. The daemon owns the layer-shell surface, the wgpu renderer, and the animation engine. Wallpaper changes render as GPU transitions from the previous image; GIFs continue playing after the transition ends, and video is decoded by FFmpeg with hardware acceleration where available.

Details: docs/architecture.md.

Troubleshooting

error while loading shared libraries: libavutil.so.58 — the installed binary was built against an older FFmpeg ABI. Reinstall the latest release (statically linked), or rebuild from source:

cargo install --path wallr --force

Wallpaper intercepts input — it shouldn't; the surface runs on Layer::Background with KeyboardInteractivity::None and an empty input region. If it happens: confirm your compositor is supported, check compositor logs for layer-shell errors, restart the daemon (pkill wallr && wallr daemon), and on niri add a layer-shell rule permitting Wallr on the background layer.

Documentation

Changelog · CLI reference · Config reference · Animation authoring · Architecture · Matugen integration · Video wallpapers

Last wallpaper per output is stored at ~/.cache/wallr/last_wallpaper/<OUTPUT> — see CLI reference and Architecture.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.