Skip to content
SPECIFICTION
Get listed

Waypaper

github.com

Free plan Open source macOSLinux
Visit github.com
Spec score 8.0 #10 of 34 in Desktop Wallpaper Software

What it is

Waypaper is a free graphical wallpaper setter for Linux window managers and macOS. It provides a single interface for backends such as swaybg, swww, awww, wallutils, hyprpaper, mpvpaper, gslapper, feh, xwallpaper, linux-wallpaperengine, and macOS. It supports multiple monitors and can restore a wallpaper when a window manager launches. The interface also offers Vim-style keyboard navigation, caching, a distraction-free Zen mode, post-change script hooks, and customizable CSS theming. Animated wallpaper support depends on the backend: selected backends handle GIFs, while mpvpaper, gslapper, or linux-wallpaperengine can provide video wallpapers. Waypaper needs at least one supported wallpaper backend installed to work. On Linux, installation options include pipx and packages or repositories for Arch-based distributions, NixOS, OpenSUSE, and Fedora. macOS setup requires GTK3 and PyGObject through Homebrew before Waypaper is installed with pipx. The repository identifies the project as GPL-3.0 licensed. Its documentation names Roman Anufriev as developer and says development began in 2023.

Spec sheet

What it does
Waypaper is a graphical wallpaper setter that fronts external wallpaper backends.Read 15 Oct 2026 · github.com
Support
The maintainer invites contributions and lists donations via cards/PayPal and several cryptocurrencies; no formal support service is stated.Read 3 Oct 2026 · github.com
License
The source repository contains the GNU General Public License version 3 dated 29 June 2007.Read 15 Oct 2026 · raw.githubusercontent.com
Founded
2023Read 28 Sep 2026 · github.com
Additional features
The documentation lists caching, a distraction-free Zen mode, post-change script hooks, and customizable CSS theming.Read 3 Oct 2026 · anufrievroman.gitbook.io
Animated GIFs
GIF wallpapers work through selected backends including swww, awww, mpvpaper and gslapper.Read 15 Oct 2026 · anufrievroman.gitbook.io
Animated wallpapers
GIF animations are supported through selected backends, and video wallpapers through mpvpaper, gslapper, or linux-wallpaperengine.Read 3 Oct 2026 · anufrievroman.gitbook.io
Backend integrations
It acts as a frontend for wallpaper backends including swaybg, swww, awww, wallutils, hyprpaper, mpvpaper, gslapper, feh, xwallpaper, linux-wallpaperengine, and macOS.Read 3 Oct 2026 · github.com
CLI controls
Command-line options include random selection, folder selection, direct wallpaper setting, backend choice, monitor targeting and fill mode.Read 15 Oct 2026 · anufrievroman.gitbook.io
Community limit: configuration reliability
A Reddit commenter reported occasional startup cases where the configuration became empty and no wallpaper appeared.Read 15 Oct 2026 · reddit.com
Community limit: startup persistence
A Reddit user reported that Waypaper did not remember the wallpaper after reboot until advised to configure --restore.Read 15 Oct 2026 · reddit.com
Community usability issue
A Reddit user initially thought backend and folder controls were missing because Zen mode hid them; pressing Z resolved the issue.Read 15 Oct 2026 · reddit.com
Configuration
The first run creates a configuration file typically at ~/.config/waypaper/config.ini.Read 15 Oct 2026 · anufrievroman.gitbook.io
Dependencies
Documented dependencies include GTK Python bindings, Pillow, imageio, imageio-ffmpeg, screeninfo and platformdirs.Read 15 Oct 2026 · anufrievroman.gitbook.io
Developer and start year
The documentation identifies Roman Anufriev as developer and says development began in 2023.Read 15 Oct 2026 · anufrievroman.gitbook.io
Documentation depth
Published documentation covers installation, usage, keybindings, configuration, troubleshooting and contribution.Read 15 Oct 2026 · anufrievroman.gitbook.io
Independent feature confirmation
LinuxLinks independently confirms Wayland, Xorg, animated GIF, video, multi-monitor, Vim-key and restore capabilities.Read 15 Oct 2026 · linuxlinks.com
Installation channels
Installation is documented through pipx, Arch AUR, NixOS packages, Fedora repositories and macOS Homebrew prerequisites.Read 15 Oct 2026 · anufrievroman.gitbook.io
Installation requirement
Users install Waypaper and at least one supported wallpaper backend for it to work as a frontend.Read 3 Oct 2026 · github.com
JSON listing
The --list option outputs current wallpapers, monitors and backend information as JSON.Read 15 Oct 2026 · anufrievroman.gitbook.io
Keyboard navigation
The interface provides Vim-style keyboard navigation.Read 15 Oct 2026 · anufrievroman.gitbook.io
Latest release
Version 2.9 was released on 30 August 2026 and added GUI slideshows, improved macOS support, Zen mode and several fixes.Read 15 Oct 2026 · github.com
Linux distributions
The project documents pipx installation and packages or repositories for Arch-based distributions, NixOS, OpenSUSE, and Fedora.Read 3 Oct 2026 · github.com
macOS setup
The README says macOS installation requires GTK3 and PyGObject via Homebrew before installing Waypaper with pipx.Read 3 Oct 2026 · github.com
macOS support
The documentation lists native macOS support using the macOS backend.Read 15 Oct 2026 · anufrievroman.gitbook.io
Maintainer profile
GitHub identifies the account as Roman and shows 17 public repositories and 102 followers.Read 15 Oct 2026 · github.com
Maker and start date
The documentation identifies Roman Anufriev as the developer and says development began in 2023.Read 3 Oct 2026 · anufrievroman.gitbook.io
Multiple monitors
Multiple-monitor wallpapers are supported, with behavior depending on the backend.Read 15 Oct 2026 · github.com
Packaging evidence
Fedora’s package review identifies Waypaper as a GUI wallpaper setter for Wayland and Xorg that fronts swaybg, swww, wallutils and feh.Read 15 Oct 2026 · bugzilla.redhat.com
Packaging limitation
The Fedora package review was closed as a dead review after the submitter did not clear a NEEDINFO request.Read 15 Oct 2026 · bugzilla.redhat.com
Post-change hooks
A post_command setting can execute a script after wallpaper changes and exposes wallpaper and monitor variables.Read 15 Oct 2026 · anufrievroman.gitbook.io
Praise: lightweight
LinuxLinks describes Waypaper as lightweight, fast and minimal with a small footprint.Read 15 Oct 2026 · linuxlinks.com
Public API
The published documentation exposes command-line interfaces but does not document a network API or SDK.Read 15 Oct 2026 · anufrievroman.gitbook.io
Security and compliance
The project pages opened do not state security certifications or compliance claims.Read 3 Oct 2026 · github.com
Self-hosting
Waypaper is distributed as local Python software and the source code is publicly available on GitHub.Read 15 Oct 2026 · github.com
Slideshow
The GUI includes a slideshow panel that runs the waypaperd daemon at a configurable interval.Read 15 Oct 2026 · anufrievroman.gitbook.io
Theming
Users can supply a custom CSS stylesheet to change the GTK interface appearance.Read 15 Oct 2026 · anufrievroman.gitbook.io
Video wallpapers
Video wallpapers are supported through mpvpaper, gslapper or linux-wallpaperengine.Read 15 Oct 2026 · anufrievroman.gitbook.io
Wallpaper restoration
The --restore command restores the last wallpaper when added to a window-manager startup configuration.Read 15 Oct 2026 · anufrievroman.gitbook.io
Wallpaper restore
It can restore the wallpaper when the window manager launches.Read 3 Oct 2026 · anufrievroman.gitbook.io
Wayland support
It supports Wayland through swww, awww, swaybg, hyprpaper, mpvpaper, gslapper and wallutils.Read 15 Oct 2026 · github.com
Xorg support
It supports Xorg through feh, xwallpaper and wallutils.Read 15 Oct 2026 · github.com

Plans and prices

Waypaper Free Free and open source Requires at least one wallpaper backend · Desktop application Read 15 Oct 2026 · github.com

Every Waypaper plan and price →

Strong points and limits

Strong points

  • Supports multiple monitors.
  • Can restore wallpaper when a window manager launches.
  • Offers Vim-style keyboard navigation.
  • Supports video wallpaper through selected backends.
  • GPL-3.0 licensed.

Limits

  • Requires at least one supported wallpaper backend.
  • macOS setup requires GTK3 and PyGObject via Homebrew.
  • Video and GIF support depends on backend.

Who it suits

Waypaper suits Linux window-manager and macOS users who want a graphical interface for setting wallpapers. It is especially relevant to users who can install and configure a compatible backend.

Verdict

Waypaper provides a configurable wallpaper interface across Linux window managers and macOS. Its usefulness depends on installing a supported backend, and some wallpaper types are available only with particular backends.

Where Specifiction places it

Alternatives to WaypaperAll alternatives →