awww

Animated Wayland wallpaper manager

TLDR

Set a wallpaper image

$ awww img [path/to/image]

Set wallpaper on specific monitors

$ awww img -o [output1,output2] [path/to/image]

Set wallpaper with a transition effect

$ awww img --transition-type [wipe] --transition-duration [1] [path/to/image]

Restore the last set wallpaper

$ awww restore

Clear the screen with a solid color

$ awww clear [RRGGBB]

Query current output and wallpaper information

$ awww query

Stop the daemon

$ awww kill

awww ("An Answer to your Wayland Wallpaper Woes") is a wallpaper manager for Wayland compositors. It controls the awww-daemon at runtime to change monitor backgrounds, supporting animated GIFs, various image formats, and smooth transition effects between wallpapers.The daemon must be started first with awww-daemon, then the awww client sends commands to control wallpaper settings. Per-output wallpaper control allows different images on multiple monitors. Processed images are cached for optimization.

PARAMETERS

-o, --outputs names

Target specific displays (comma-separated).

-f, --filter filter

Scaling filter: Nearest, Bilinear, CatmullRom, Mitchell, Lanczos3.

--resize mode

Resize mode: no, crop, fit, stretch.

--no-resize

Disable resizing; center image instead.

--fill-color RRGGBB

Padding color for unfilled areas (default: 000000).

-t, --transition-type type

Effect: none, simple, fade, left, right, top, bottom, wipe, wave, grow, center, any, outer, random.

--transition-step n

RGB increment per frame (0-255).

--transition-duration seconds

Transition completion time in seconds.

--transition-fps n

Transition frame rate (max 255).

--transition-angle degrees

Angle for wipe and wave transitions.

--transition-pos position

Circle center position for grow and outer effects.

--transition-bezier curve

Custom cubic-bezier animation curve.

--transition-wave width,height

Wave dimensions for wave transition.

-n, --namespace name

Target a specific Wayland namespace.

-a, --all

Target all active namespaces.

COMMANDS

img path

Set wallpaper image or animated GIF. Use - to read from stdin.

restore

Re-display the previously shown image on outputs.

clear color

Fill specified outputs with a solid color.

clear-cache

Remove the awww cache directory.

query

Request daemon output details (names and dimensions).

kill

Terminate the daemon process.

CAVEATS

Requires a compositor implementing the wlr-layer-shell protocol (typically wlroots-based compositors like Sway or Hyprland). Does not work with GNOME or KDE. The daemon must be running before setting wallpapers. Animated wallpapers consume more resources than static images.

HISTORY

awww is the renamed successor to swww, created by LGFae. The project was renamed from "A Solution to your Wayland Wallpaper Woes" to "An Answer to your Wayland Wallpaper Woes" and moved from GitHub to Codeberg in October 2025. It focuses on efficiency and smooth animations while maintaining low resource usage. Released under GPL-3.0.