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

-c, --config path
    Set a custom config file path. Defaults to ~/.config/hypr/hyprpaper.conf.

--verbose
    Enable more verbose logging output.

-v, --version
    Print hyprpaper's version and exit.

-h, --help
    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
    Monitor ID to target. Leave empty to use this wallpaper as a fallback for any monitor without a specific assignment.

path
    Path to an image file, or a directory containing image files. Required.

fit_mode
    How to display the image. One of contain, cover, tile, or fill. Defaults to cover.

timeout
    Seconds between wallpaper changes when path is a directory. Defaults to 30.

order
    Order in which images are shown when path is a directory. Currently the only supported value is random.

recursive
    Whether to scan subdirectories recursively when path is a directory. Defaults to false.

  Global options
These options are set outside any wallpaper { } block.

splash
    Render the Hyprland splash over the wallpaper. Boolean, defaults to true.

splash_offset
    How far up the splash is displayed. Float, defaults to 20.

splash_opacity
    Opacity of the splash (0.0–1.0). Float, defaults to 0.8.

ipc 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