swaybg(1)
Set the desktop background image for Wayland compositors running Sway.
Synopsis
swaybg [-o <output>] [-m <mode>] [-c <color>] <image>Description
swaybg is a wallpaper utility for Wayland compositors, primarily designed for Sway. It sets a background image or solid color on one or all outputs. Unlike X11 tools, swaybg integrates directly with the Wayland protocol to manage desktop backgrounds.
The command accepts an image file path and applies scaling modes to fit your display. If no image is provided, you can set a solid background color instead. Multiple invocations can set different backgrounds on different outputs.
Common options
| Flag | What it does |
|---|---|
-o, --output <output> | Target a specific output/monitor by name (e.g., HDMI-1, eDP-1); omit to apply to all outputs |
-m, --mode <mode> | Set scaling mode: stretch, fill, fit, center, or tile (default: stretch) |
-c, --color <color> | Set background color as hex code (e.g., #000000 for black) or solid color without image |
-h, --help | Display help message and exit |
-v, --version | Show version information |
Examples
Set a wallpaper in fill mode (scales to cover output, may crop edges)
swaybg -m fill ~/Pictures/wallpaper.pngScale image to fit without cropping, using dark gray for letterbox areas
swaybg -m fit -c '#1e1e1e' ~/Pictures/bg.jpgSet centered background on the HDMI-1 monitor only
swaybg -o HDMI-1 -m center ~/Pictures/image.pngSet a solid dark blue background color across all outputs
swaybg -c '#0a0e27'Set a repeating tile pattern on laptop display, run in background
swaybg -m tile -o eDP-1 ~/Pictures/pattern.png &Stretch image to fill entire output (may distort aspect ratio)
swaybg -m stretch ~/wallpapers/4k.png