Skip to the content
Know your tech before you buy it. Makers: get listed from $49/mo

Waypaper

github.com

  • Free plan
  • Open source
  • macOS
  • Linux
7.8 Club score Visit github.com

What Waypaper is

Waypaper is a free graphical wallpaper setter for Linux window managers and macOS. It acts as a frontend for supported wallpaper backends, including swaybg, swww, awww, wallutils, hyprpaper, mpvpaper, gslapper, feh, xwallpaper, linux-wallpaperengine, and macOS; at least one compatible backend is required. It supports multiple monitors, Vim-style keyboard navigation, and restoring wallpaper when a window manager launches. GIF animation support depends on selected backends, while mpvpaper, gslapper, and linux-wallpaperengine support video wallpapers. The documentation also lists caching, a distraction-free Zen mode, post-change script hooks, and customizable CSS theming. Linux installation options include pipx and packages or repositories for Arch-based distributions, NixOS, OpenSUSE, and Fedora. For macOS, setup requires GTK3 and PyGObject via Homebrew before installing Waypaper with pipx. The GitHub repository identifies the project as GPL-3.0 licensed. Its documentation names Roman Anufriev as the developer and says development began in 2023.

Who it suits

Waypaper may suit Linux window-manager and macOS users who want a graphical interface for wallpaper backends. It is also relevant to users who need multi-monitor support or backend-dependent animated wallpapers.

Good to know, and what to watch

  • Supports multiple monitors.
  • Provides Vim-style keyboard navigation.
  • Can restore wallpaper when a window manager launches.
  • Documents caching, Zen mode, and CSS theming.
  • GPL-3.0 licensed.
  • Requires at least one compatible wallpaper backend.
  • GIF and video support depend on backend.
  • macOS setup requires GTK3 and PyGObject via Homebrew.

Waypaper

Free

Free plan

The verdict

Waypaper is a free frontend for wallpaper backends, with multi-monitor support and several interface options. Setup requires a compatible backend, and animated wallpaper capabilities vary by backend.

What the maker publishes

Additional features
The documentation lists caching, a distraction-free Zen mode, post-change script hooks, and customizable CSS theming. source
Animated GIFs
GIF wallpapers work through selected backends including swww, awww, mpvpaper and gslapper. source
Animated wallpapers
GIF animations are supported through selected backends, and video wallpapers through mpvpaper, gslapper, or linux-wallpaperengine. source
Backend integrations
It acts as a frontend for wallpaper backends including swaybg, swww, awww, wallutils, hyprpaper, mpvpaper, gslapper, feh, xwallpaper, linux-wallpaperengine, and macOS. source
CLI controls
Command-line options include random selection, folder selection, direct wallpaper setting, backend choice, monitor targeting and fill mode. source
Community limit: configuration reliability
A Reddit commenter reported occasional startup cases where the configuration became empty and no wallpaper appeared. source
Community limit: startup persistence
A Reddit user reported that Waypaper did not remember the wallpaper after reboot until advised to configure --restore. source
Community usability issue
A Reddit user initially thought backend and folder controls were missing because Zen mode hid them; pressing Z resolved the issue. source
Configuration
The first run creates a configuration file typically at ~/.config/waypaper/config.ini. source
Dependencies
Documented dependencies include GTK Python bindings, Pillow, imageio, imageio-ffmpeg, screeninfo and platformdirs. source
Developer and start year
The documentation identifies Roman Anufriev as developer and says development began in 2023. source
Documentation depth
Published documentation covers installation, usage, keybindings, configuration, troubleshooting and contribution. source
Founded
2023 source
Independent feature confirmation
LinuxLinks independently confirms Wayland, Xorg, animated GIF, video, multi-monitor, Vim-key and restore capabilities. source
Installation channels
Installation is documented through pipx, Arch AUR, NixOS packages, Fedora repositories and macOS Homebrew prerequisites. source
Installation requirement
Users install Waypaper and at least one supported wallpaper backend for it to work as a frontend. source
JSON listing
The --list option outputs current wallpapers, monitors and backend information as JSON. source
Keyboard navigation
The interface supports Vim-style keyboard navigation. source
Keyboard navigation
The interface provides Vim-style keyboard navigation. source
Latest release
Version 2.9 was released on 30 August 2026 and added GUI slideshows, improved macOS support, Zen mode and several fixes. source
License
The GitHub repository identifies the project as GPL-3.0 licensed. source
License
The source repository contains the GNU General Public License version 3 dated 29 June 2007. source
Linux distributions
The project documents pipx installation and packages or repositories for Arch-based distributions, NixOS, OpenSUSE, and Fedora. source
macOS setup
The README says macOS installation requires GTK3 and PyGObject via Homebrew before installing Waypaper with pipx. source

Checked against the maker's pages on 15 Oct 2026.