Usage

waypaper command will run GUI application. Make sure to choose the backend that you installed.

To restore your wallpaper at launch, add waypaper --restore to your startup config. For example:

In Hyprland

exec-once=waypaper --restore

In Sway or I3

exec waypaper --restore

To see the list of hotkeys, press ?.

CLI options

--restore - sets the last chosen wallpaper. Useful at launch of the window manager.

--random - sets a random wallpaper.

--folder path/to/folder - sets folder of wallpaper images.

--wallpaper path/to/image.jpg - sets the wallpaper without running the GUI.

--backend XXX - specifies which backend to use. Accepted values: swaybg, swww, awww, hyprpaper, mpvpaper, gslapper, feh, xwallpaper, wallutils, linux-wallpaperengine, macos. Useful if you use waypaper on both Wayland and Xorg on the same machine. By default, the last used backend is used.

--monitor NAME - specifies the target monitor by name. If omitted, the wallpaper is set on all monitors.

--fill XXX - specifies filling type, which can be either fill, stretch, fit, center, or tile.

--list - list current wallpapers, monitors and backend in standard output in json format.

--state-file path/to/file - sets alternative path to state file.

--config-file path/to/file - sets alternative path to configuration fiile.

--no-post-command - prevents running the post_command set in config.

--zen-mode - launches in Zen mode, which hides the top bar and options panel for a minimal, grid-only view. Zen mode can also be toggled from the options menu or with a hotkey.

Automatically changing wallpaper

From the GUI (slideshow)

The simplest way is the built-in slideshow. Enable the slideshow panel from the options menu, set an interval in minutes, and start it. Waypaper runs a small background daemon (waypaperd) that changes to a random wallpaper on that interval, and stops it when you press stop.

If you also add waypaper --restore to your startup config, the slideshow resumes automatically after a reboot when it was left enabled.

Simple bash script

The most basic way to automatically change wallpaper at set intervals is to run a simple script:

while true; do sleep 600; waypaper --random; done

You can start it with the start of your system, for example.

Cron job

For a more sophisticated solution, create these two files:

~/.config/systemd/user/waypaper.timer

[Unit]
Description=Set a random wallpaper every minute

[Timer]
Persistent=true
OnCalendar=*:0/1

[Install]
WantedBy=timers.target

~/.config/systemd/user/waypaper.service

[Unit]
Description=Set a random wallpaper with waypaper

[Service]
Type=oneshot
ExecStart=waypaper --random

Note, depending on how waypaper is installed, you may need to provide a full path to the executable in ExecStart.

To test, run $ systemctl --user start waypaper.timer To make persistent, run $ systemctl --user enable waypaper.timer