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 (preload, set, and unload unused)

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

List preloaded wallpapers

$ hyprctl hyprpaper listloaded

List active wallpapers with monitors

$ hyprctl hyprpaper listactive

SYNOPSIS

hyprpaper
Control 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

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.