HYPRPAPER(1)

📦
version 0.8.4 · 2 versions
, in ubuntu stonking

💖 HYPRPAPER 💖

okay bestie, gather round, because we're talking about hyprpaper — the fast, IPC-controlled wallpaper utility for Hyprland. that's it. that's the whole job. it makes your desktop gorgeous and it does it FAST. no cap. ✨

so basically hyprpaper reads a config file to set per-monitor wallpapers, and it also lets you control everything at runtime through hyprctl(1) because it's a main character with IPC support. the config file? literally optional. you can run this whole thing off IPC alone. iconic behavior honestly. 💅

🌸 SYNOPSIS 🌸

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

that's it, that's the whole vibe. short and slay. 🎀

✨ OPTIONS ✨

  • -c, --config path — bestie, use this when you want a custom config file path instead of the default one. the default is ~/.config/hypr/hyprpaper.conf if you don't say anything. 🫶
  • --verbose — turn on more verbose logging output so you can see everything happening. perfect for when you're being nosy (affectionate). 🔍
  • -v, --version — prints hyprpaper's version and then dips. exit stage left. 👑
  • -h, --help — shows the help menu</help> and exits. your little cheat sheet, no shame in it. 🌈

🦋 CONFIGURATION 🦋

your config lives at ~/.config/hypr/hyprpaper.conf. but hear me out — it is not required. fr fr. hyprpaper can be controlled entirely via IPC if that's your thing. do whatever feels right. 😌

💜 Wallpaper blocks

wallpapers get declared inside wallpaper blocks. you can have multiple blocks, go wild. and here's the cute part: a block with an empty monitor field acts as a fallback for any monitor that never got assigned a specific wallpaper. so thoughtful. so giving.

wallpaper {
    monitor   = DP-3
    path      = ~/myFile.jxl
    fit_mode  = cover
}

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

and these are the options you can put inside a wallpaper { } block, bestie:

  • monitor — the monitor ID you're targeting. leave it empty and this wallpaper becomes the fallback for any monitor without a specific assignment. it's giving backup bestie energy. 💖
  • path — path to an image file, or a directory full of image files. this one is required. no path, no wallpaper, no slay. ⚠️
  • fit_mode — how the image gets displayed. one of contain, cover, tile, or fill. defaults to cover. ✨
  • timeout — seconds between wallpaper changes when path is a directory. defaults to 30. so if you're doing a slideshow, this is your tempo. ⏱️
  • order — the order images are shown in when path is a directory. rn the only supported value is random. keep that in mind, don't get creative. 🎲
  • recursive — whether to scan subdirectories recursively when path is a directory. defaults to false. 🗂️

🌟 Global options

these ones get set outside any wallpaper { } block. top-level energy.

  • 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 — the opacity of the splash, on a scale of 0.0–1.0. float, defaults to 0.8. ✨
  • ipc — enable IPC support. boolean, defaults to true. 💅

🌈 Sourcing

you can pull in extra files with the source keyword. globbing, tilde expansion, and relative paths are all supported. and processing is linear — lines before source get parsed first. in order. no jumping around. 😤

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

🔥 IPC 🔥

hyprpaper does IPC through hyprctl(1). so if you wanna set a wallpaper at runtime, boom:

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

mon can be left empty if you want the fallback target. fit_mode is optional, no pressure. and important detail bestie: the fallback wallpaper only applies to monitors that have never had a specific monitor target assigned. so if you already gave a monitor its own assignment, the fallback is not coming for it. periodt. 💀

👑 AUTOSTART 👑

want hyprpaper to just... already be there when Hyprland boots? mood. add this line to ~/.config/hypr/hyprland.conf:

exec-once = hyprpaper

and if you're starting Hyprland with uwsm, you've got another option — you can enable the provided systemd user service:

systemctl --user enable --now hyprpaper.service

autostart via systemd? that's main character energy fr. 🌟

🍓 FILES 🍓

  • ~/.config/hypr/hyprpaper.conf — Default configuration file. your home base. 🏠

🧚 SEE ALSO 🧚

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

the whole friend group honestly. go say hi. 🫶

💖 AUTHORS 💖

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

that's the whole page bestie!! 🌸 this was hyprpaper v0.8.4, documented on 2026-05-02, brought to you with love by the Hypr Development team and contributors. now go set a wallpaper and go be iconic. mwah 💋✨

📦 where this page comes from