hyprpaper

official wallpaper utility for Hyprland

TLDR

Start the hyprpaper service

$ hyprpaper

Preload a wallpaper

$ hyprctl hyprpaper preload "[path/to/image.png]"

Switch wallpaper to a different preloaded image

$ hyprctl hyprpaper wallpaper "[monitor],[path/to/image.png]"

Reload wallpaper (set/change without preloading first)

$ hyprctl hyprpaper reload "[monitor],[path/to/image.png]"

Set wallpaper on all monitors (empty monitor field)

$ hyprctl hyprpaper wallpaper ",[path/to/image.png]"

Unload all preloaded wallpapers

$ hyprctl hyprpaper unload all

List preloaded wallpapers

$ hyprctl hyprpaper listloaded

SYNOPSIS

hyprpaperControl via: hyprctl hyprpaper command [arguments]

hyprpaper is the official wallpaper utility for Hyprland. It runs as a background service and allows dynamic wallpaper changes without restarting.Configuration is stored in ~/.config/hypr/hyprpaper.conf with directives:

$ preload = /path/to/image.png
wallpaper = monitor,/path/to/image.png

The preload system allows fast wallpaper switching by keeping images in memory. Use listloaded to track memory usage and unload to free unused wallpapers.

PARAMETERS

preload PATH

Load wallpaper into memory for quick switching

wallpaper MONITOR,PATH

Set wallpaper on specified monitor

reload MONITOR,PATH

Preload, set, and unload unused wallpapers

unload PATH

Remove wallpaper from memory

listloaded

Show preloaded wallpapers

listactive

Show active wallpapers per monitor

INSTALL

sudo pacman -S hyprpaper

sudo zypper install hyprpaper

nix profile install nixpkgs#hyprpaper

CAVEATS

Requires Hyprland to be running. Preloaded wallpapers consume memory. Large images or many preloaded wallpapers can impact system resources. Monitor names must match Hyprland output names.

HISTORY

hyprpaper was created as part of the Hyprland ecosystem by Vaxry. It provides wallpaper functionality specifically designed for Hyprland's Wayland implementation, with IPC integration for dynamic control.