Configuration
The Sweetbg config file
Sweetbg reads one TOML file:
$XDG_CONFIG_HOME/sweetbg/config.toml
~/.config/sweetbg/config.tomlEvery 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 = 24There is no hot reload. Run sweetbg reload after editing.
Keys
| Key | Default | Description |
|---|---|---|
image | none | Absolute path to a JPEG, PNG, or WebP file |
color | "#1e1e2e" | Background as "#rrggbb", or "auto" |
fit | "cover" | How the image fills the output |
blur | 0 | Blur 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
| Mode | Behavior |
|---|---|
cover | Fill the output, crop the overflow |
contain | Fit the whole image, fill the margins with color |
center | Native size, centered. Cropped or padded as needed |
tile | Repeat at native size |
span | Stretch 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, andblurwork here.coloris global. spancan't be set per output.
Unknown or malformed keys are errors. The message includes the file and line number.