Waypaper is a GTK3 front end for wallpaper backends, not a wallpaper engine

Waypaper delegates the painting, so it needs a backend beside it

Waypaper does not draw wallpapers on its own. It is a GTK3 interface that drives a separate wallpaper program on your machine, so the real decisions happen in two places: the toolkit that renders the window, and the backend that actually paints the image. The README is explicit that the project "works as a frontend for popular wallpaper backends", and setup.py lists PyGObject, platformdirs, Pillow, imageio, imageio-ffmpeg and screeninfo as install requirements, with python_requires set to '>3.10'. That split keeps the application small. The README quotes its size as 315 kB. It also means a fresh install with no backend present gives you a picture browser and a command that fails. Installing at least one backend is the first step in the project's own setup instructions, not an optional extra.

Which backends you pick decides which features you get

The backend list changes with your display server. On Wayland the README names awww, swww, swaybg, hyprpaper, wallutils, mpvpaper and gslapper. On Xorg it lists feh, xwallpaper and wallutils. On macOS the built-in macos backend does the work, and setup.py still registers the usual Linux desktop files, so the packaging is not fully macOS native. Feature support is decided per backend rather than globally. Multiple monitors work with awww, swaybg, hyprpaper or mpvpaper. GIF animations work with awww, mpvpaper or gslapper. Video wallpapers work with mpvpaper or gslapper. The dependency list also marks socat as required only for the mpvpaper backend, where it serves the IPC socket. If you install swaybg and later want an animated wallpaper, you have to add a second backend.

Installing the frontend with pipx, yay or a distribution package

Waypaper is a Python package, so the shortest path on any distribution is pipx. The README lists that route under the heading for all distributions, and warns that pipx itself may need installing first since some package managers call it python-pipx. Start by installing a backend from your package manager, because Waypaper cannot set anything on its own, then install the frontend.

pipx install waypaper

On Arch-based systems the AUR carries both a stable waypaper package and a waypaper-git developer package.

yay -S waypaper

Waypaper is also packaged for NixOS, and on Fedora it is available through an external repository owned by Solopasha. Running waypaper with no arguments starts the graphical application.

Restoring the wallpaper after a reboot needs your startup config

Waypaper can reapply the wallpaper after a restart, but it does not do that on its own. The README shows the restore mode as a command line flag, and you add that command to your window manager startup configuration.

waypaper --restore

Two entry points are registered in setup.py. The gui_scripts entry maps waypaper to waypaper.__main__:run, and the console_scripts entry maps waypaperd to waypaper.waypaperd:main. The restore path matters after a reboot because your session starts before any wallpaper program is running, so something has to reissue the request. The README does not describe a packaged service unit for this, which puts the work on the startup file you already keep for your window manager.

The slideshow panel in the GUI and the separate waypaperd daemon

Wallpaper rotation is not tied to the graphical window. The README describes a slideshow panel that you open from the options menu in the interface, where you set an interval and start the rotation. Separately, setup.py ships a console entry point named waypaperd, so the slideshow can run as a daemon outside the graphical session, which matters for setups where the session starts before your desktop is ready. The README does not list the daemon's own command line flags. The documentation site, linked from the README under the entry for automatically changing wallpaper, is where the other ways of running the slideshow daemon are described. If you intend to script the rotation instead of clicking through the panel, that page is the place to check for the exact invocation before you wire it into a startup file.

Feature gaps are inherited from the backend, not from the GUI

The main limitation follows directly from the architecture. Waypaper exposes a common interface over programs that do not do the same things, so the reachable feature set is the union of what your installed backend supports, never more. A user on Xorg with only feh installed has no path to animated wallpapers, since the README restricts GIF support to awww, mpvpaper or gslapper and video support to mpvpaper or gslapper. Steam's Wallpaper Engine animated wallpapers need the separate linux-wallpaperengine program, which the README lists as an optional add-on. Another boundary sits around automation: the only non-GUI invocation shown in the README is the restore flag, and everything else, including how the daemon takes its arguments, lives in the external documentation rather than in the repository.

Distribution packages need extra steps on OpenSUSE, Fedora and macOS

Installation is not uniform across platforms. On OpenSUSE the README points to a reported installation issue and names two packages that must be installed first, python313-pycairo-devel and python313-gobject-devel, because the pipx route fails without them. On Fedora the package comes from a COPR repository rather than the distribution archive.

sudo dnf copr enable lionheartp/Hyprland
sudo dnf install waypaper

On macOS, GTK3 and PyGObject have to come from Homebrew before the pipx install will work.

brew install gtk+3 pygobject3
pipx install waypaper

To make the application reachable from Spotlight and Launchpad, the README has you copy the provided app bundle into your Applications folder.

cp -r data/macos/Waypaper.app ~/Applications/

A GPL-3.0 project with one maintainer and a slow release rhythm

Waypaper is published under GPL-3.0, and setup.py repeats that as the license field with the matching GNU General Public License classifier. The release history is small and dated: version 2.9 shipped on 2026-08-30, 2.8 on 2026-03-31 and 2.7 on 2025-09-28. The last push to the repository was on 2026-08-31, so the project is receiving work, and the 2.9 release brought the slideshow panel. The project states that it is not developed professionally but in free time, and the contribution notes ask for small adjustments, no whole-codebase automatic formatting and an issue before large changes. The top-level tree is lean, with the application in a waypaper directory, a data directory, a tests directory and the usual packaging files. Translation work is expected to go through the translations.py file.

Editorial conclusion

Waypaper suits people who want a single graphical control panel for wallpapers across Wayland, Xorg and macOS and who are willing to install a backend that matches the features they actually want. It is the wrong choice if you need animated or multi monitor output while running only swaybg or feh, or if you want wallpaper rotation driven entirely by a script with no GUI involved. Before adopting, confirm that the backend you plan to install covers the feature you need, check that waypaper --restore runs from your window manager startup config, and read the CLI options page for the flags of the release you install.

Frequently asked questions

Official sources

1. anufrievroman/waypaper on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases