Waypaper
github.com
- Free plan
- Open source
- macOS
- Linux
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.
Plans
Every plan and priceWaypaper
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.