swaybg

Set the wallpaper to an image

$ swaybg [[-i|--image]] [path/to/image]

$ swaybg [[-i|--image]] [path/to/image] [[-m|--mode]] [stretch|fit|fill|center|tile|solid_color]

$ swaybg [[-c|--color]] "[#rrggbb]"

swaybg [options...]
swaybg -m mode -i image_path
swaybg -c color

-m, --mode mode
    Sets the scaling mode for the image. Possible values are fill, fit, stretch, center, and tile. This option is required when using an image.

-i, --image path
    Specifies the path to the image file to use as wallpaper. This option cannot be used with --color.

-c, --color color
    Sets a solid background color. The color can be specified as a hexadecimal value (e.g., #RRGGBB or #AARRGGBB) or a CSS color name. This option cannot be used with --image.

-o, --output output
    Specifies the name of the output (e.g., DP-1, HDMI-A-1) to apply the background to. This option can be used multiple times to set different backgrounds for different outputs. If omitted, the background applies to all outputs.

-u, --update
    Updates an existing swaybg instance instead of starting a new one. This is useful for changing the wallpaper without flickering or restarting swaybg.

-v, --version
    Shows the version information of swaybg and exits.

-h, --help
    Shows a help message describing command options and usage, then exits.

swaybg is a command-line utility specifically designed to set backgrounds for outputs within the Sway Wayland compositor. It allows users to display image files as wallpapers or fill the background with a solid color. The tool supports various scaling modes for images, including fill, fit, stretch, center, and tile, providing flexibility in how backgrounds are presented across different screens.

It can apply distinct backgrounds to individual outputs or a single background across all active outputs. swaybg is a lightweight and efficient solution, often integrated directly into Sway's configuration file to automatically manage desktop backgrounds upon startup or when output configurations change. Its simplicity and native integration make it the standard wallpaper utility for the Sway environment.

swaybg is designed specifically for the Sway Wayland compositor and will not work with X11 or other Wayland compositors. When specifying multiple outputs using -o, each output must be immediately followed by its corresponding -i (image) or -c (color) option. For image backgrounds, ensure the image file path is correct and the file is accessible; otherwise, the background may not display.

swaybg is most commonly invoked directly within the Sway configuration file (e.g., ~/.config/sway/config) using the `output` command. For example, to set a background for all outputs, you might use:
output * bg /path/to/image.jpg fill
or for a solid color:
output * bg #000000 solid_color

This method allows Sway to manage swaybg instances automatically. Alternatively, swaybg can be run as a standalone process via `exec`, for example:
exec swaybg -m fill -i /path/to/image.jpg

When run, swaybg typically operates as a persistent background process, continuously managing the wallpaper for the specified outputs. If the swaybg process terminates, the wallpaper may disappear or revert to a default state. Using the --update (-u) flag is crucial for changing the wallpaper dynamically without stopping and restarting the process, which helps avoid screen flickering and conserves resources.

swaybg was developed as an integral part of the Sway ecosystem to provide native wallpaper management for the Wayland compositor. Its creation addressed the incompatibility of traditional X11 wallpaper tools, like feh, with Wayland's display architecture. It aims to be a lightweight and efficient background setter, designed to integrate seamlessly with Sway's output management, and has evolved alongside the Sway project itself.

sway(5), sway-output(5), feh(1)