wpaperd-output(5) File Formats Manual wpaperd-output(5)

# [NAME](#NAME)

wpaperd-output - format used by wpaperd to define the various displays

# [DESCRIPTION](#DESCRIPTION)

The wpaperd configuration file contains the information about each display, the corresponding wallpaper and its settings. This file is located in XDG\_CONFIG\_HOME/wpaperd/config.toml (which defaults to $HOME/.config/wpaperd/config.toml).

# [SYNTAX](#SYNTAX)

This file is a simple TOML configuration divided in sections, one for each display.

## [SECTION](#SECTION)

Each section is named after the display identifier. If you are using *sway*, you can lookup the output identifier by calling:

```
$ swaymsg -t get_outputs
```

On Hyprland, you can do it with:

```
$ hyprctl monitors
```

The configuration file for **wpaperd** is located in \`XDG\_CONFIG\_HOME/wpaperd/config.toml\` (which defaults to \`~/.config/wpaperd/config.toml\`). Each section represents a different display and can contain the following keys:

- \`path\`, path to the image to use as wallpaper or to a directory to pick the wallpaper from
- \`duration\`, how much time the image should be displayed until it is changed with 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\`, with the default being \`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 corner, changing the aspect ratio - \`tile\` shows the image multiple times horizontally and vertically to fill the screen
- \`transition\_time\`, how many milliseconds should the transition run. (*Optional*, \`300\` by default).
- \`queue\_size\`, decide how big the queue should be when \`path\` is set 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](#DEFAULT_SECTION)

The section "**default**" will be used as base for the all the display configuration; the section "**any**" will be used for all the displays that are not explictly listed. This allows to have a flexible configuration without repeating any settings. *wpaperd* will check the configuration at startup and each time it changes and provide help when it is incorrect.

# [EXAMPLE](#EXAMPLE)

The simplest configuration looks like this:

```
[DP-3]
path = "/home/danyspin97/github_octupus.png"
[DP-4]
path = "/home/danyspin97/Wallpapers"
duration = "30m"
```

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](#AUTHOR)

Maintained by Danilo Spinella <danilo.spinella@suse.com>.

2026-10-16

---

Document: wpaperd-output(5) from wpaperd 1.3.0-r0 (Chainguard OS)