Skip to main content
otter-wallpaper draws backgrounds on the Wayland background layer through zwlr_layer_shell_v1. It decodes each image to an SHM buffer, then frees it to keep memory use low.

​
Usage

Autostart at login: see Session setup.

​
Pick or randomize a wallpaper

Use these as compositor keybindings:
The picker shows images from the configured folder. Click one to apply it, or press Escape to close. --random chooses another image and respects blocklist. A running wallpaper daemon reloads the updated config immediately.

​
Configuration

Config file: ~/.config/otter-shell/otter-wallpaper.conf
Per-display overrides use display_0_name, display_0_path, through display_7_*.

​
Lockscreen integration

On wallpaper change, otter-wallpaper writes the current path per output to:
Format: one output_name=path line per output. otter-lock reads this file for the lock screen background. otter-theme-gen uses the same state to build wallpaper-reactive themes.

​
Niri overview

With overview_enabled = true, it creates a blurred layer surface with namespace otter-wallpaper-overview. Add to your Niri config:
That surface is Niri’s own overview backdrop. The Otter Shell overlay is a separate app: otter-overview.

​
Hot reload

Config and theme changes apply through inotify, with no restart. Reload keeps the current wallpaper.