Papyrus is a free, open-source wallpaper manager for Wayland compositors that support the layer-shell protocol. Pick a video or image, click it, and it becomes your wallpaper — no accounts, no telemetry, no Wallpaper Engine required.
Built primarily for COSMIC desktop. Papyrus uses mpvpaper, which requires a compositor that implements wlr-layer-shell (such as wlroots-based compositors). GNOME/Mutter and KDE Plasma do not currently support this protocol, so animated wallpapers will not work there. Papyrus reports this limitation when it detects the protocol error.
It also automatically extracts the dominant color from your wallpaper and applies it as your COSMIC accent color, so your entire desktop theme matches your wallpaper vibe. Auto-theming is a COSMIC-only extra.
- 🎬 Animated and static wallpapers — supports MP4, WebM, MKV, AVI, MOV, JPEG, PNG, WebP, and BMP
- 🖥️ Per-monitor wallpapers — set different videos or images on each monitor independently
- 📐 Per-monitor scaling — choose Fit, Fill, or Stretch for each output
- 🔄 Playlist rotation — auto-switch wallpapers at a set interval (random or sequential order)
- 🎨 Auto-theme (COSMIC) — extracts accent color from wallpaper and applies it to your COSMIC theme
- 🌙 Auto dark/light mode — detects wallpaper brightness and switches accordingly
- 📁 Folder picker — choose any folder of video or image files to scan
- 🖼️ Thumbnail previews — auto-generated from your wallpaper files
- 🔁 Start on login — one toggle to persist your wallpaper across reboots
- ⬆️ Self-update — app checks for updates and can download & install them with one click
- 🚫 No telemetry, no accounts, no cloud — config is a plain JSON file
Flatpak support has ended. The Papyrus Flatpak in the COSMIC Store is no longer maintained or supported. For supported installations, use the universal installer, the
.debpackage, or the AUR package below.
The universal installer detects your distro and handles everything:
curl -fsSL https://raw.githubusercontent.com/PSGtatitos/papyrus/main/install.sh | bashSupports: Pop, Ubuntu, Debian, Fedora, openSUSE. Arch-based users should use the AUR package instead.
AUR (Arch Linux / CachyOS / Manjaro) Install from the AUR using your preferred AUR helper:
yay -S papyrus-wallpaper
# or
paru -S papyrus-wallpaperDependencies (mpvpaper, python-gobject, gtk4, etc.) are handled automatically.
.deb package (Debian/Ubuntu/Pop) Download the latest .deb from the releases page and install:
sudo apt install ./papyrus_*.debThe .deb bundles mpvpaper and includes all dependencies.
Flatpak builds are no longer supported. Please use one of the supported installation methods above.
Local install: Run ./update.sh or re-run the installer. The app can also self-update from the banner. .deb install: Download the latest .deb from the releases page and reinstall. Flatpak: no longer maintained or supported. AUR: Updated via your AUR helper (yay -Syu or paru -Syu). Usage Launch Papyrus from your app launcher or run:
papyrusClick any thumbnail to set it as your wallpaper
Folder button (top left) to add wallpaper folders
Playlist tab in Settings to enable auto-rotation with configurable interval (random or sequential)
Rotation continues in the background after the Papyrus window is closed. Enable Start on Login as well to resume rotation automatically after logging in.
Auto-theme (COSMIC) toggle to enable/disable automatic COSMIC theming
Stop button (top right) to remove the wallpaper
Update banner appears automatically when a new version is available
Where to find animated wallpapers
MoeWalls — anime/gaming, optimized WebM/MP4
MotionBGs — 8,000+ wallpapers in 4K
Wallsflow — growing collection, free
Pexels Videos — cinematic/nature, 4K
How it works
Papyrus uses mpvpaper to render video and image files as Wayland layer surfaces behind your desktop. This requires compositor support for wlr-layer-shell. When you select a wallpaper, Papyrus:
Kills any running mpvpaper instance Starts mpvpaper with loop enabled on your display output Extracts the most vibrant pixel from the wallpaper thumbnail Writes the color to COSMIC's compiled theme config files (COSMIC only) COSMIC picks up the file changes and updates the accent color Auto-theming When Auto-theme (COSMIC) is enabled, Papyrus writes directly to:
~/.config/cosmic/com.system76.CosmicTheme.Dark/v1/accent ~/.config/cosmic/com.system76.CosmicTheme.Dark/v1/background ~/.config/cosmic/com.system76.CosmicTheme.Mode/v1/is_dark No restart required — COSMIC watches these files and applies changes live.
Config is stored at ~/.config/papyrus/config.json:
{ "current": "/home/user/Wallpapers/Papyrus/my-wallpaper.mp4", "dirs": ["/home/user/Wallpapers/Papyrus"], "output": "HDMI-A-1", "auto_theme": true, "rotation": true, "interval": 30, "order": "random" }
Local install:
rm ~/.local/bin/papyrus
rm ~/.local/share/applications/io.github.PSGtatitos.papyrus.desktop
rm ~/.local/share/icons/hicolor/256x256/apps/io.github.PSGtatitos.papyrus.png
rm -rf ~/.config/papyrus
rm -f ~/.config/autostart/papyrus.desktop
update-desktop-database ~/.local/share/applications.deb install:
sudo apt remove --purge papyrus
rm -rf ~/.config/papyrusAUR:
yay -Rns papyrus-wallpaper
rm -rf ~/.config/papyrusFlatpak:
flatpak uninstall io.github.PSGtatitos.papyrusPull requests are welcome. For major changes, open an issue first.
Built with assistance from: Claude (Anthropic) was used as a coding assistant during development.
GPL-3.0 — same license as mpvpaper.