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 (non recursively) 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 
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.conf and add: exec-once = hyprpaper.
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. You can set wallpapers like so:

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

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.

Last updated on
hyprpicker