osfeed.dev
Projects/hyprwm / hyprpaper

hyprpaper

A wallpaper utility for Hyprland

by@hyprwm·Runs on Linux
Get it on GitHub
Unclaimed

Written by @iluxav from the project's code and releases, not by its maintainers. Last updated for v0.8.5 (2026-11-01), so it may lag behind newer releases.

Are you @hyprwm?Claim it, and your coding agent keeps it current with each release
v0.8.5 · 7 things you can do 1.4k stars 7 changes to know before upgrading

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 hyprpaper

Set a wallpaper for each monitor, or one for all monitors, from a config file.

Present at v0.7.1
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.

Share
Wrong?

Change the wallpaper while hyprpaper runs, for example a different one per workspace from a key binding.

Present at v0.7.1
Good to know

Only preloaded images switch instantly; unload images you no longer need to free memory.

Share
Wrong?

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

Since v0.8.1
Good to know

One interval per wallpaper block.

Share
Wrong?

Before you upgrade hyprpaper

Newest first
v0.8.1

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
Share
Wrong?
v0.8.1

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
Read the evidence
Share
Wrong?
Show 4 older
hyprpaper release history 9
v0.8.5

Rotate wallpapers with IPC disabled without crashing on a timed change.

Details

With `ipc = 0`, timed wallpaper changes now skip IPC notification when no socket exists, avoiding the null-socket crash.

Available in v0.8.5 for Linux; the README lists Hyprland and the hyprtoolkit, hyprlang, hyprutils and hyprwire build dependencies.

Now works / inferred: Cycle through several images or a whole folder, cha…

Seeded by @iluxav with Codex

Read the evidence
v0.8.4

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…

Seeded by @iluxav with Claude Code

Read the evidence
v0.8.3

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…

Seeded by @iluxav with Claude Code

Read the evidence
v0.8.1

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

Seeded by @iluxav with Claude Code

Read the evidence
v0.7.6

Split your hyprpaper config across several files.

Details

A source = <path> line includes another config file.

v0.7.6.

Added: Include other config files from hyprpaper.conf with…

Seeded by @iluxav with Claude Code

Read the evidence
v0.7.5

Keep building hyprpaper from source with a current wayland-protocols.

Details

The build now requires wayland-protocols 1.35 or newer.

v0.7.5.

Action required

Seeded by @iluxav with Claude Code

Read the evidence
v0.7.4

Show wallpapers the right way up on rotated monitors.

Details

hyprpaper now applies the monitor's transform (wl_output transform), so rotated displays get a correctly oriented wallpaper.

v0.7.4.

Now works / inferred: Set a wallpaper for each monitor, or one for all mo…

Seeded by @iluxav with Claude Code

Read the evidence
v0.7.3

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

Seeded by @iluxav with Claude Code

Read the evidence
v0.7.1
Starting point

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.

Seeded by @iluxav with Claude Code

Read the evidence

Share

LinkedIn takes the link and its card only; write your text there.

X LinkedIn Reddit Hacker News Bluesky