hyprpaper
Set Hyprland wallpapers
TLDR
Start the hyprpaper service
Preload a wallpaper
Switch wallpaper to a different preloaded image
Preload a wallpaper, set that wallpaper, then unload all unused wallpapers
List the wallpapers that are currently preloaded (useful for dynamically preloading and unloading)
List the active wallpapers hyprpaper is displaying, along with their associated monitor
SYNOPSIS
hyprpaper [-c|--config PATH]
PARAMETERS
-c, --config PATH
Path to config file. Default: $XDG_CONFIG_HOME/hypr/hyprpaper.conf
-h, --help
Show usage help and exit
DESCRIPTION
Hyprpaper is a lightweight, dedicated wallpaper utility for the Hyprland Wayland compositor. It manages static and animated wallpapers across multiple monitors with minimal overhead.
Key functionality includes preloading images into memory to prevent stuttering during switches, per-monitor wallpaper assignment, and runtime control via Hyprland's IPC system. Configuration occurs in a simple text file (~/.config/hypr/hyprpaper.conf) using directives like preload = path/to/image.png to load assets and wallpaper = monitor,path/to/image.png to apply them (omit monitor for all outputs).
Supports PNG, JPEG, WebP, and more; animated formats require additional tools like mpvpaper. Start as a daemon with exec-once = hyprpaper in Hyprland config. Dynamically adjust via hyprctl hyprpaper commands, e.g., hyprctl hyprpaper wallpaper "DP-1,/path.png".
Features splash rendering on startup and hot-reloading. Ideal for dynamic setups with scripts or keybinds, emphasizing performance in C++.
CAVEATS
Exclusive to Hyprland compositor; incompatible with X11 or other Wayland compositors like Sway.
Images must be preloaded for stutter-free application.
Requires Hyprland >= v0.20 for full IPC support.
CONFIG EXAMPLE
preload = ~/wall.png
splash = true
wallpaper = ,~/wall.png
wallpaper = DP-1,~/desk.png
IPC COMMANDS
hyprctl hyprpaper preload ~/img.png
hyprctl hyprpaper wallpaper "eDP-1,~/img.png"
hyprctl hyprpaper clear "eDP-1"
HISTORY
Introduced in 2022 with early Hyprland releases by developer Vaxry. Evolved from community needs for a swaybg/mpvpaper alternative, gaining IPC controls and multi-format support by v0.25+. Actively maintained within Hyprland ecosystem.
