Scroll to navigation

HYPRPAPER(1) User Commands HYPRPAPER(1)

NAME

hyprpaper - fast, IPC-controlled wallpaper utility for Hyprland

SYNOPSIS

hyprpaper [-c path] [--verbose] [-v] [-h]

DESCRIPTION

hyprpaper is a fast, IPC-controlled wallpaper utility for Hyprland. It reads a configuration file to set per-monitor wallpapers and supports runtime control via hyprctl(1).

OPTIONS

Set a custom config file path. Defaults to ~/.config/hypr/hyprpaper.conf.
Enable more verbose logging output.
Print hyprpaper's version and exit.
Show the help menu and exit.

CONFIGURATION

The configuration file is located at ~/.config/hypr/hyprpaper.conf. It is not required; hyprpaper can be controlled entirely via IPC.

Wallpaper blocks

Wallpapers are declared in wallpaper blocks. Multiple blocks may be specified. A block with an empty monitor field acts as a fallback for monitors that have not been assigned a specific wallpaper.

wallpaper {


    monitor   = DP-3


    path      = ~/myFile.jxl


    fit_mode  = cover
}
wallpaper {


    monitor   =


    path      = ~/fallback.jxl


    fit_mode  = cover
}

The following options are recognized inside a wallpaper { } block:

Monitor ID to target. Leave empty to use this wallpaper as a fallback for any monitor without a specific assignment.
Path to an image file, or a directory containing image files. Required.
How to display the image. One of contain, cover, tile, or fill. Defaults to cover.
Seconds between wallpaper changes when path is a directory. Defaults to 30.
Order in which images are shown when path is a directory. Currently the only supported value is random.
Whether to scan subdirectories recursively when path is a directory. Defaults to false.

Global options

These options are set outside any wallpaper { } block.

Render the Hyprland splash over the wallpaper. Boolean, defaults to true.
How far up the splash is displayed. Float, defaults to 20.
Opacity of the splash (0.0–1.0). Float, defaults to 0.8.
Enable IPC support. Boolean, defaults to true.

Sourcing

Additional files can be included with the source keyword. Globbing, tilde expansion, and relative paths are supported. Processing is linear: lines before source are parsed first.

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

IPC

hyprpaper supports IPC via hyprctl(1). To set a wallpaper at runtime:

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

mon may be left empty for the fallback target. fit_mode is optional. The fallback wallpaper only applies to monitors that have never had a specific monitor target assigned.

AUTOSTART

To launch hyprpaper automatically with Hyprland, add the following line to ~/.config/hypr/hyprland.conf:

exec-once = hyprpaper

If Hyprland is started with uwsm, you may alternatively enable the provided systemd user service:

systemctl --user enable --now hyprpaper.service

FILES

~/.config/hypr/hyprpaper.conf
Default configuration file.

SEE ALSO

hyprland(1), hyprctl(1), hyprpicker(1)

AUTHORS

The Hypr Development team and contributors.
https://github.com/hyprwm/hyprpaper

2026-05-02 hyprpaper v0.8.4