Skip to Content
Matuwall

Usage

Keys, favorites, lists and applying wallpapers without the picker

Keyboard

KeyAction
Arrows, h j k lMove the selection. Carousel movement wraps
Page Up, Page DownMove one page. Disabled in carousel mode
Home, gFirst tile
End, GLast tile
rRandom tile
fMark as favorite
BackspaceGo back to the wallpaper you started with
EnterApply and close
EscapeCancel and close

Mouse

Mouse input is off by default:

[input]
mouse = true

Hover selects, the wheel moves and left click applies. With preview on, clicking outside the panel cancels.

Without the Picker

These apply a wallpaper and exit. No window opens. Backend and hooks run exactly like Enter.

CommandAction
matuwall --restoreApply the last wallpaper again
matuwall --randomApply a random wallpaper, never the current one
matuwall --nextApply the next wallpaper
matuwall --prevApply the previous wallpaper

Restore wallpaper and colors at login, e.g. in your compositor autostart:

matuwall --restore

--next and --prev follow sort and wrap at both ends. They combine with other options:

matuwall --random -d ~/Pictures/Photography

Favorites

Press f to mark the selected wallpaper. Marked wallpapers are written to the favorites file when the picker closes:

~/.config/matuwall/favorites.txt

Open them later:

matuwall --list ~/.config/matuwall/favorites.txt

To remove a favorite, edit the file.

Wallpaper Lists

Pick from a file with one path per line instead of a directory. - reads stdin:

matuwall --list ~/favorites.txt
fd -e jpg sunset ~/Pictures | matuwall --list -
# favorites.txt
~/Pictures/Wallpapers/forest.jpg
city/night.png
  • Relative paths are inside the first directory. From stdin, they use the current directory
  • Blank lines and # comments are skipped
  • The grid keeps the list order unless sort = "color"
  • --next, --prev and --random work on lists too

Stay Open After Apply

[window]
close_on_apply = false

Enter applies in the background, so you can try several wallpapers in a row. Backspace goes back and re-applies the starting wallpaper.

Files

PathContents
~/.config/matuwall/config.tomlConfig
~/.config/matuwall/favorites.txtFavorites
~/.local/state/matuwall/last-selectionLast applied wallpaper
~/.local/state/matuwall/matuwall.logLog, limited to 256 KiB plus two rotations
~/.cache/matuwall/thumbs/Thumbnail cache
~/.cache/matuwall/colorsLearned colors for sort = "color"

XDG base directory variables are respected.

Maintenance

matuwall --diagnose      # check config, Wayland, backends, hooks and paths
matuwall --clear-cache   # remove cached thumbnails only

On this page