wpaperd-output(5)

💅 wpaperd-output — the glam little manual page for your displays ✨

okay so bestie, welcome to wpaperd-output(5) — literally the manual for the format wpaperd uses to define all your displays 🖥️💖. Pull up a chair, we're gonna get you looking iconic.

---

🌸 NAME 🌸

wpaperd-output — the format wpaperd uses to define the various displays 🫶

---

✨ DESCRIPTION ✨

the wpaperd config file is where all the display gossip lives: every display, its corresponding wallpaper, and all its settings 🎀. this file sits at XDG_CONFIG_HOME/wpaperd/config.toml, which defaults to $HOME/.config/wpaperd/config.toml. no cap, that's the one 💅

---

🦋 SYNTAX 🦋

it's a simple TOML configuration, divided into sections — one section per display. that's it, that's the vibe ⭐

🎀 SECTION 🎀

each section is named after the display identifier 👑. need to find yours?

if you're on sway, look up the output identifier by calling:

$ swaymsg -t get_outputs

on Hyprland, you do it with:

$ hyprctl monitors

the config file for wpaperd lives in XDG_CONFIG_HOME/wpaperd/config.toml (which defaults to ~/.config/wpaperd/config.toml) 📁. each section = a different display, and it can contain these keys:

• path — the path to the image you wanna use as wallpaper, or a path to a directory to pick the wallpaper from 🖼️
• duration — how much time the image should be displayed until it gets changed for a new one ⏳. it supports a human format for declaring the duration (e.g. 30s or 10m), described [here](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html). this is only valid when path points to a directory. (Optional)
• sorting — choose the sorting order. valid options are ascending, descending, and random, and the default is random 🎲. this is only valid when path points to a directory. (Optional)
• mode — choose how to display the wallpaper when the size is different than the display resolution:
  • fit — shows the entire image with black corners covering the empty space left 🖤
  • center — centers the image on the screen, leaving out the corners of the image that couldn't fit 🎯
  • stretch — shows the entire image stretching it to fit the entire screen without leaving any black corners, changing the aspect ratio 😮‍💨
  • tile — shows the image multiple times horizontally and vertically to fill the screen 🧩
• transition_time — how many milliseconds the transition should run for. (Optional, 300 by default)
• queue_size — decide how big the queue should be when path is set to a directory and sorting is set to random. (Optional, 10 by default)
• initial_transition — whether or not to transition from the initial black screen. (Optional, true by default)

💜 DEFAULT SECTION 💜

okay this part is so good, listen:

the section "default" gets used as the base for all the display configurations 🫶. and the section "any" gets used for all the displays that are not explicitly listed. so you get a flexible config without repeating any settings — literally so efficient, we love to see it ✨. wpaperd checks the configuration at startup and each time it changes, and it will provide help when it's incorrect 🙏 (it's got your back).

---

🔥 EXAMPLE 🔥

the simplest configuration looks like this:

[DP-3]
path = "/home/danyspin97/github_octupus.png"

[DP-4]
path = "/home/danyspin97/Wallpapers"
duration = "30m"

and a more complex configuration is also possible 👀:

[default]
duration = "30m"
mode = "center"
sorting = "ascending"

[any]
path = "/home/danyspin97/default_wallpaper.png"

[DP-3]
path = "/home/danyspin97/Wallpapers"

---

👑 AUTHOR 👑

maintained by Danilo Spinella <danilo.spinella@suse.com> 💌

---

fr fr, double-check your path values before you @ me — wpaperd will help you out at startup if something's off, but nobody wants a broken vibe check 😭

---

that's the whole page, bestie! 🎀 this one's from the wpaperd-output(5) File Formats Manual, dated 2026-06-24 — go forth and make your desktop absolutely iconic 🌈💖🦋