Release / 2 Jan 2026

hyprpaper v0.8.1

Rotate wallpapers on a timer from a list of images or a whole folder.

All of hyprpaper

Before you upgrade to v0.8.1

4 to fix

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

Read the evidence

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 requiredChange the wallpaper while hyprpaper runs, for example a different one per workspace from a key binding.Affects: Scripts and key bindings that call hyprctl hyprpaperInferred

Read the evidence

splash_color is gone; remove it from the config. splash_opacity sets the text's opacity.

Action requiredShow Hyprland's splash text over the wallpaper.Affects: Configs that set splash_colorInferred

Read the evidence

hyprpaper now refuses to start when the config has an error, instead of starting anyway.

Behavior changedAffects: Users with a config that has errors

Read the evidence

Install hyprtoolkit and hyprwire before building this release from source.

Action requiredAffects: People building hyprpaper from source

Read the evidence

What changed in v0.8.1

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.

New things you can do

path takes comma-separated images or a folder; timeout sets the seconds between changes (30 when unset).

AddedCycle through several images or a whole folder, changing the wallpaper every set number of seconds.

Read the evidence

Fixed and improved

fit_mode = cover, contain, tile or fill per wallpaper block; fill stretches the image to the screen.

ImprovedChoose whether a wallpaper covers the whole screen or fits inside it.Inferred

Read the evidence

Seeded by @iluxav with Claude Code (canido), from the release's public sources. Each change links to its evidence.