programmersd21/wallr has 201 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 20:18 UTC. Last push 2026-11-09.
What you can do
- static image wallpapers through a shared-memory fast path
- gpu transitions for images, gifs, and videos
- animated gif playback with bounded frame caching
- video playback through FFmpeg, with software fallback
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
gpu accelerated animated wallpaper engine for wayland
Creative & MediaREADME.md
Originalwallr
wallpaper engine for wayland, with gpu transitions, gif and video playback, and optional theme updates.
table of contents
- background
- features
- why wallr
- when not to use wallr
- pros and cons
- how it compares
- requirements
- installation
- build from source
- quick start
- configuration
- cli reference
- effects and transitions
- video wallpapers
- animated wallpapers
- scaling modes
- multi-monitor and hotplug
- theme integration
- hooks and reloads
- ipc and daemon
- performance
- security and safety
- troubleshooting
- documentation
- contributing
- license
- faq
background
wallr is a native wallpaper engine for wayland. it is written in rust and uses a small client plus a long-lived daemon. the daemon owns background layer-shell surfaces, renders transitions with wgpu, and plays animated or video wallpapers without asking the compositor to do wallpaper-specific work.
the project is intentionally focused. it does not try to be a desktop shell, a widget framework, or a compositor plugin. it sets wallpapers, switches them with transitions, plays media, and optionally updates theme files.
if you are coming from tools such as swww, awww, hyprpaper, or swaybg, wallr aims to give you a single command-line workflow with animated and video support, multi-monitor handling, and optional theme integration.
features
- static image wallpapers through a shared-memory fast path
- gpu transitions for images, gifs, and videos
- animated gif playback with bounded frame caching
- video playback through FFmpeg, with software fallback
- multi-monitor support and output hotplug handling
- per-output scaling modes: fill, fit, stretch, center, and tile
- optional theme generation with matugen, wallust, or pywal
- user hooks and reload commands
- ipc commands for pause, resume, seek, blank, restore, and status
- shared-memory presentation for static images
- bounded decoder queues and seek error propagation
- deterministic monitor listing
- doctor diagnostics for wayland and theme tools
- release binaries with static FFmpeg
why wallr
wallr is useful when you want more than a static image but do not want a heavy desktop shell or a compositor-specific wallpaper plugin. it keeps the wallpaper as a background layer surface, handles multiple outputs, and can switch media without restarting the daemon.
it is especially useful for:
- animated wallpapers on wlroots-based compositors
- short video loops as desktop backgrounds
- themed desktops where wallpaper changes trigger color generation
- multi-monitor setups
- users who want a command-line driven workflow
- systems where predictable memory use matters
when not to use wallr
wallr may not be the right choice if:
- your compositor does not support
wlr-layer-shell - you only need a static image and prefer the smallest possible tool
- you need x11 support
- you need a desktop shell with widgets or panels
- your hardware cannot run a wayland compositor with gpu support
- you need guaranteed universal hardware decoding on every driver
in those cases, simpler tools may be a better fit.
pros and cons
pros
- native wayland integration instead of x11 compatibility layers
- gpu-accelerated transitions and animation
- bounded memory budgets for decoded video frames
- shared-memory path for static images
- multi-output and hotplug aware
- optional theme integration
- command-line and ipc driven workflow
- open source and packaged for arch, nix, and crates.io
- diagnostics command for common setup problems
- release binaries with static FFmpeg
cons
- requires a wayland compositor with
wlr-layer-shell - hardware decoding depends on drivers and supported backends
- video playback can use significant cpu or memory on low-end systems
- some features depend on external tools such as FFmpeg or theme providers
- compositor and gpu behaviour must be verified on each target system
- animated and video wallpapers use more resources than static images
- not every compositor has been tested
how it compares
wallr is not trying to replace every wallpaper tool. it occupies a specific space: native wayland, animated and video wallpapers, transitions, and theme integration.
compared with static-image tools, wallr does more work and uses more resources, but gives smoother switching and richer media support.
compared with heavier desktop environments, wallr stays small and focused on wallpaper behaviour.
compared with compositor-specific plugins, wallr is portable across compositors
that implement wlr-layer-shell.
requirements
- a wayland compositor with
wlr-layer-shell - rust 1.90 or newer for source builds
- FFmpeg development libraries for dynamic source builds
- official static release binaries do not require a separate FFmpeg install
- for static builds, the Linux tools listed by
scripts/install-static-ffmpeg.sh
installation
cargo
cargo install wallr
this installs the wallr client and wallr-daemon.
arch linux
yay -S wallr-bin
nix
nix run github:programmersd21/wallr
release archive
download the latest archive from the
releases page, extract it,
and put both wallr and wallr-daemon on your PATH.
build from source
git clone https://github.com/programmersd21/wallr.git
cd wallr
cargo build --workspace --release --locked
for a static FFmpeg build, run ./scripts/install-static-ffmpeg.sh, then export
the variables it prints and run the same build command.
more setup and project conventions are in contributing.
quick start
wallr set wallpaper.jpg
wallr set wallpaper.jpg -e grow -o center -d 850ms
wallr set video.mp4 --fps 30
wallr ipc status
wallr set starts the daemon automatically when daemon.auto_start is enabled.
to run it manually, use wallr daemon or start wallr-daemon directly. see
the cli reference.
configuration
the default file is ~/.config/wallr/config.yaml:
wallpaper:
mode: fill
loop_video: true
theme:
provider: matugen
daemon:
auto_start: true
max_fps: 60
see the configuration reference for all options.
cli reference
common commands:
wallr set <path>
wallr set <path> -e grow -o center -d 850ms
wallr set video.mp4 --fps 30
wallr reload
wallr monitor list
wallr monitor current
wallr ipc pause
wallr ipc resume
wallr ipc seek 1:30
wallr ipc status
wallr doctor
wallr quit
use --monitor <output> to target one output where supported.
effects and transitions
wallr supports fade, wipe, slide, wave, grow, and outer transitions. duration, origin, angle, direction, easing, and effect parameters can be overridden from the command line.
examples:
wallr set wallpaper.jpg -e wipe -a 45 -d 700ms
wallr set wallpaper.jpg -e grow -o center -d 850ms
wallr set wallpaper.jpg -e wave -o 0.25,0.75
see the effects reference.
video wallpapers
video playback uses FFmpeg and supports software fallback. per-wallpaper fps caps and scaling modes are available.
wallr set video.mp4 --fps 30
wallr ipc seek 1:30
wallr ipc pause
wallr ipc resume
the decoder queues a bounded number of frames. if playback falls behind, stale frames can be dropped. presentation follows video timestamps. see video-wallpaper.md.
animated wallpapers
animated gif wallpapers are decoded on demand and cached within a bounded budget. extension handling is case-insensitive.
wallr set animation.gif
animated wallpapers support transitions, pause, resume, and theme frame extraction.
scaling modes
wallr supports:
- fill
- fit
- stretch
- center
- tile
fill is the default. fit preserves aspect ratio and leaves unused areas defined by the compositor background. center renders at native size.
multi-monitor and hotplug
wallr creates a surface for each detected output and keeps output state isolated. outputs can be targeted by name.
wallr monitor list
wallr set wallpaper.jpg --monitor DP-1
wallr ipc pause --monitor HDMI-A-1
output addition, removal, and reconfiguration are handled by the daemon.
theme integration
wallr can run theme providers after a wallpaper changes.
supported providers:
- matugen
- wallust
- pywal
- none
configuration:
theme:
provider: matugen
matugen:
enabled: true
mode: dark
scheme: scheme-tonal-spot
theme failures are reported separately and do not hide a successful wallpaper change.
hooks and reloads
hooks run before, after, or on error. reload commands run after successful wallpaper changes.
hooks:
before: []
after: []
error: []
reload:
- "pkill -USR1 some-program"
use wallr reload to reload configuration and hooks.
ipc and daemon
wallr uses a unix socket for client-daemon communication. the daemon handles wallpaper changes, playback, and output lifecycle.
wallr ipc status
wallr ipc info
wallr ipc blank
wallr ipc restore
the socket is created with restrictive permissions. oversized or malformed requests are rejected.
performance
wallr aims to avoid unnecessary work:
- static images can use shared-memory presentation
- gpu resources are reused where possible
- decoder queues are bounded
- seek errors propagate instead of being hidden
- idle static wallpapers do not require continuous rendering
performance depends on compositor, gpu, driver, media resolution, and settings.
security and safety
wallr handles local media and configuration. it validates ipc request sizes, monitor names, paths, and effect parameters. subprocesses are invoked with argument arrays rather than shell strings where possible.
unsafe code is limited to wayland handle wrappers and FFmpeg FFI. safety comments describe the invariants.
troubleshooting
- run
wallr doctorto check wayland and theme provider availability - if
WAYLAND_DISPLAYis not set, wallr cannot run - if hardware decoding fails, set
video.hw_decode: software - if a video does not play, test a still image first, then run
wallr ipc info - if theme generation fails, the wallpaper change still succeeds
- static release binaries do not need a separate FFmpeg runtime install
documentation
cli · configuration · effects · video · compositors · architecture · benchmarks · changelog
contributing
contributions are welcome. see CONTRIBUTING.md for setup, style, testing, and pull request expectations.
license
MIT. See LICENSE.
faq
does wallr support x11?
no. wallr is wayland-only.
does wallr support all compositors?
no. it requires wlr-layer-shell, which is common on wlroots-based
compositors but not universal.
can wallr play 4k video?
yes, if the system has enough cpu, memory, and gpu resources. performance depends on codec, driver, and compositor.
does wallr upload private data?
no. wallr runs locally and does not send telemetry.
can i use wallr without theme integration?
yes. set theme.provider: none or use --no-theme.
is wallr production ready?
wallr is actively developed. core functionality is tested, but compositor and gpu behaviour must be verified on your system.
