hyprpaper

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

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. Relative paths are resolved relative to the working directory from which hyprpaper was started	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

Examples

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.

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

Last updated on August 29, 2026

hyprpicker