Skip to content
Hypr Ecosystem
hyprpaper

hyprpaper

hyprpaper is a fast, IPC-controlled wallpaper utility for Hyprland.

Installation

Arch 
pacman -S hyprpaper
openSUSE 
zypper install hyprpaper
Fedora 
sudo dnf install hyprpaper

Configuration

The config file is located at ~/.config/hypr/hyprpaper.conf. It is not required.

Setting wallpapers

Wallpapers are set as anonymous special categories. Monitor can be left empty for a fallback.

variable description value
monitor Monitor to display this wallpaper on. If empty, will use this wallpaper as a fallback monitor ID
path Path to an image file or a directory containing image files path
fit_mode Determines how to display the image. Optional and defaults to cover contain|cover|tile|fill
timeout Timeout between each wallpaper change (in seconds, if path is a directory). Optional and defaults to 30 seconds int
order Determines the order to display images when a directory is passed to the path option. Optional, currently only supported value is random random
recursive Whether to scan subdirectories recursively when path is a directory. Optional and defaults to false bool 
wallpaper {
    monitor = DP-3
    path = ~/myFile.jxl
    fit_mode = cover
}

wallpaper {
    monitor = DP-2
    path = ~/myFile2.jxl
    fit_mode = cover
}

wallpaper {
    monitor = 
    path = ~/fallback.jxl
    fit_mode = cover
}

# ...

Run at Startup

To run hyprpaper at startup edit hyprland.lua and add hyprpaper to your autostart commands.
If you start Hyprland with uwsm, you can also use the systemctl --user enable --now hyprpaper.service command.

Misc Options

These should be set outside of the wallpaper{...} sections.

variable description type default
splash enable rendering of the hyprland splash over the wallpaper bool true
splash_offset how far up should the splash be displayed float 20
splash_opacity how opaque the splash is float 0.8
ipc whether to enable IPC bool true

Sourcing

Use the source keyword to source another file. Globbing, tilde expansion and relative paths are supported.

source = ~/.config/hypr/hyprpaper.d/*.conf

Please note it’s LINEAR. Meaning lines above the source = will be parsed first, then lines inside ~/.config/hypr/hyprpaper.d/*.conf files, then lines below.

IPC

hyprpaper supports IPC via hyprctl.

Supported requests:

hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]'
hyprctl hyprpaper listactive

wallpaper sets wallpapers like so:

hyprctl hyprpaper wallpaper '[mon], [path], [fit_mode]'

where fit_mode is optional, and mon can be empty for a fallback, just like in the config file. The fallback wallpaper only applies to monitors that have never had a specific monitor target assigned.

listactive prints the currently active wallpaper for each monitor, for example:

hyprctl hyprpaper listactive
HDMI-A-1: /home/user/wallpapers/wp1.jpg
eDP-1: /home/user/wallpapers/wp2.jpg

Notice, that older examples may mention preload, reload, unload, or listloaded; check hyprctl hyprpaper --help for the requests supported by your installed version.

Last updated on
hyprpicker