Sweets

Configuration

The Sweetbg config file

Sweetbg reads one TOML file:

$XDG_CONFIG_HOME/sweetbg/config.toml
~/.config/sweetbg/config.toml

Every key is optional. A missing file uses the defaults.

image = "/home/me/Pictures/wallpaper.jpg"
color = "#1e1e2e"
fit = "cover"
blur = 0

[output.DP-1]
image = "/home/me/Pictures/left.jpg"
fit = "contain"
blur = 24

There is no hot reload. Run sweetbg reload after editing.

Keys

KeyDefaultDescription
imagenoneAbsolute path to a JPEG, PNG, or WebP file
color"#1e1e2e"Background as "#rrggbb", or "auto"
fit"cover"How the image fills the output
blur0Blur sigma in logical pixels, integer 0–100. 0 disables it

color shows before an image is set and around contain and center images. "auto" picks the image's dominant color, so the margins match the wallpaper.

image must be a file. For a random image from a folder, run sweetbg img ~/Pictures/Wallpapers/ --persist instead.

Strings are double-quoted. blur is a bare integer.

Blur

blur is applied once, when the wallpaper is prepared. It covers the fitted image and the color margins. The displayed wallpaper stays static, but preparing it takes extra time and temporary memory.

With span, each output's slice is blurred on its own.

Fit modes

ModeBehavior
coverFill the output, crop the overflow
containFit the whole image, fill the margins with color
centerNative size, centered. Cropped or padded as needed
tileRepeat at native size
spanStretch one image across all outputs

span needs xdg-output support from the compositor. Without it, it falls back to cover.

Per-output settings

An [output.NAME] section overrides image, fit, or blur for one output. sweetbg query lists the output names.

[output.HDMI-A-1]
image = "/home/me/Pictures/tv.png"

# Background color only on this output
[output.eDP-1]
image = ""
  • Only image, fit, and blur work here. color is global.
  • span can't be set per output.

Unknown or malformed keys are errors. The message includes the file and line number.

On this page