swww

Set wallpaper

$ swww img [path/to/image]

$ swww img [[-o|--outputs]] [output1,output2,...] [path/to/image]

$ swww restore

$ swww kill

$ swww query

swww init
swww img [OPTIONS] <PATH>
swww clear [OPTIONS]
swww query
swww stop
swww kill

-o, --output <NAME>
    Specifies the output(s) to apply the wallpaper. Use '*' for all, or a comma-separated list of monitor names.

-t, --transition-type <TYPE>
    Defines the type of transition effect for changing wallpapers (e.g., 'fade', 'wipe', 'grow', 'center', 'outer').

-d, --transition-duration <DURATION>
    Sets the duration of the transition in milliseconds.

-e, --transition-easing <EASING>
    Specifies the easing function for the transition animation (e.g., 'linear', 'ease', 'ease-in', 'ease-out').

--resize <RESIZE_TYPE>
    Controls how the image is resized to fit the screen (e.g., 'zoom', 'crop', 'fit', 'center').

--fill <COLOR>
    Specifies a hexadecimal color to fill empty areas when the image doesn't cover the entire screen (e.g., with 'fit' resize type).

swww is a command-line utility designed to set wallpapers on Wayland compositors. Unlike traditional X11 wallpaper setters, swww is specifically built for the Wayland environment, providing robust support for various image formats including static images (PNG, JPEG, etc.), animated GIFs, and even video formats (with appropriate libraries). It leverages the
wlr-layer-shell protocol for placement and wlroots for rendering, making it compatible with a wide range of Wayland compositors such as Sway, Hyprland, River, and others that use wlroots. swww also features wallpaper caching for faster loading, support for multiple outputs, and various animation styles for smooth transitions when changing wallpapers. It operates as a client that sends commands to a background daemon (swww-daemon) which handles the actual rendering and updates, ensuring persistent wallpapers and efficient resource usage.

swww is exclusively designed for Wayland compositors that implement the wlr-layer-shell protocol (e.g., Sway, Hyprland, River). It will not function in X11 environments. The swww-daemon must be running (usually initiated via 'swww init') for the client commands like 'swww img' to work. Support for certain video formats might require additional system libraries like ffmpeg.

swww operates in a two-part model: a long-running swww-daemon which handles the actual rendering and display of wallpapers, and a client swww command-line tool that sends instructions to the daemon. This architecture ensures efficient management and quick updates of wallpapers without restarting processes, and allows for continuous animation playback.

It is crucial to understand that swww is built from the ground up for Wayland. It leverages Wayland-specific protocols and libraries, meaning it is incompatible with traditional X11 display servers. Users migrating from X11 should note that familiar X11 wallpaper tools like feh or nitrogen will not work with Wayland, and swww serves as a native Wayland solution.

swww emerged to fill a critical gap in Wayland's ecosystem: a robust and feature-rich wallpaper manager, particularly for animated backgrounds like GIFs. Unlike early Wayland wallpaper solutions such as swaybg, which lacked advanced animation and transition capabilities, swww provided dynamic desktop experiences. Its development has focused on seamless integration with wlroots-based compositors, performance optimization, and expanding its array of visual effects, making it a popular choice for modern Wayland desktop setups.

sway(1), hyprctl(1), feh(1) (X11 alternative), nitrogen(1) (X11 alternative), wallutils(1)