Built by @hyprwm on GitHub. This page was written by @iluxav from public sources, last updated for v0.8.4 (2026-04-29), and may lag behind new releases.
Set a wallpaper on each monitor of your Hyprland desktop, choose how it fits the screen, and rotate through a folder of images.
What you can do with it
Set a wallpaper for each monitor, or one for all monitors, from a config file.
Good to know
An image must be preloaded before it can be shown, and each preloaded image stays in memory (about 8 to 20 MB). The config is not reloaded when it changes. PNG, JPEG and WebP.
Present at v0.7.1
Choose whether a wallpaper covers the whole screen or fits inside it.
Present at v0.7.1
Change the wallpaper while hyprpaper runs, for example a different one per workspace from a key binding.
Good to know
Only preloaded images switch instantly; unload images you no longer need to free memory.
Present at v0.7.1
Show Hyprland's splash text over the wallpaper.
Present at v0.7.1
Start hyprpaper at login with a systemd user service.
Since v0.7.3
Include other config files from hyprpaper.conf with source.
Since v0.7.6
Cycle through several images or a whole folder, changing the wallpaper every set number of seconds.
Good to know
One interval per wallpaper block.
Since v0.8.1
Before you upgrade
Newest first
v0.8.12026-01-02
Rewrite hyprpaper.conf: replace preload = and wallpaper = <monitor>,<path> lines with wallpaper { monitor = <name>, path = <image>, fit_mode = <mode> } blocks; contain: and tile: prefixes become fit_mode = contain or tile.
Action requiredAffects: Every existing hyprpaper.conf
The hyprctl hyprpaper preload, wallpaper, unload, listloaded and listactive commands are no longer handled; IPC is now a hyprwire protocol socket (hw-protocols/hyprpaper_core.xml). Scripts that call them need a client for the new protocol.
Action requiredInferredAffects: Scripts and key bindings that call hyprctl hyprpaper
Shuffle a wallpaper folder, including its subfolders.
Details
order = random or random-shuffle changes the slideshow order; recursive = 1 also takes images from subfolders; the protocol gains a status object for reading hyprpaper's state.
v0.8.4.
Improved: Cycle through several images or a whole folder, cha…
Pick a monitor by its description again, or use * for a default wallpaper on every monitor.
Details
monitor = desc:<description> matches by description again (dropped in the 0.8 rewrite); monitor = * sets the default for all monitors; hyprpaper --version prints the version. Groups v0.8.2 and v0.8.3.
v0.8.3.
Improved: Set a wallpaper for each monitor, or one for all mo…
Rotate wallpapers on a timer from a list of images or a whole folder.
Details
Rewritten on hyprtoolkit (v0.8.0) with a new config: wallpaper { monitor = ..., path = ..., fit_mode = cover|contain|tile|fill } blocks instead of preload and wallpaper = lines. path can list several images or a folder, changed every timeout seconds (30 when unset). Groups v0.8.0 and v0.8.1.
Also: splash_opacity; hyprpaper refuses to start with an invalid config; source = came back in v0.8.1.
v0.8.1; building needs hyprtoolkit, hyprlang, hyprutils and hyprwire.
Added: Cycle through several images or a whole folder, cha…Action requiredImproved / inferred: Choose whether a wallpaper covers the whole screen…Action required / inferred: Change the wallpaper while hyprpaper runs, for exam…Action required / inferred: Show Hyprland's splash text over the wallpaper.Behavior changedAction required
Tile a small image across the screen as your wallpaper.
Details
A tile: prefix on the wallpaper path repeats the image; JPEG XL images load; a systemd user service is installed. Groups v0.7.2 and its crash-fix release v0.7.3.
Also: JPEG XL support.
v0.7.3; building now needs hyprgraphics and newer hyprlang (0.6.0) and hyprutils (0.2.4).
Improved: Choose whether a wallpaper covers the whole screen…Improved: Set a wallpaper for each monitor, or one for all mo…Added: Start hyprpaper at login with a systemd user servic…Action required
Set a different wallpaper on each monitor from one config file.
Details
State as of v0.7.1: ~/.config/hypr/hyprpaper.conf with preload = <image> and wallpaper = <monitor>,<image> lines; contain: before the path for contain mode; hyprctl hyprpaper preload, wallpaper, unload, listloaded and listactive.
Packaged for Arch and openSUSE; builds with CMake.
Added: Set a wallpaper for each monitor, or one for all mo…Added: Choose whether a wallpaper covers the whole screen…Added: Change the wallpaper while hyprpaper runs, for exam…Added: Show Hyprland's splash text over the wallpaper.
