Papyrus

Animated wallpaper manager for any Wayland desktop

Papyrus is a free, open-source animated wallpaper manager for any Wayland desktop. Pick a video, click it, and it becomes your live wallpaper — no accounts, no telemetry, no Wallpaper Engine required.

Built primarily for the COSMIC desktop, but it runs on any Wayland compositor (COSMIC, GNOME, Hyprland, Sway, KDE Wayland, OMarchy, and more) because it uses mpvpaper under the hood.

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 — wallpapers themselves work everywhere.)

Features

• 🎬 Animated wallpapers — supports MP4, WebM, MKV, AVI, MOV
• 🖥️ Per-monitor wallpapers — set different videos 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 files to scan
• 🖼️ Thumbnail previews — auto-generated from your video 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

COSMIC Store

Papyrus is available in the cosmic-flatpak repository and can be installed directly from the COSMIC Store. You can also install manually.

Installation

Quick install (any distro)

The universal installer detects your distro and handles everything:

curl -fsSL https://raw.githubusercontent.com/PSGtatitos/papyrus/main/install.sh | bash

Supports: 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-wallpaper

Dependencies (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_*.deb

The .deb bundles mpvpaper and includes all dependencies.

COSMIC Store (Flatpak) Search for "Papyrus" in the COSMIC Store or run:

flatpak install io.github.PSGtatitos.papyrus

Updating

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: Updated automatically via the COSMIC Store. AUR: Updated via your AUR helper (yay -Syu or paru -Syu). Usage Launch Papyrus from your app launcher or run:

papyrus

Click 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) 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 files as Wayland layer surfaces behind your desktop. 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 video 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

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" }

Uninstall

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/papyrus

AUR:

yay -Rns papyrus-wallpaper
rm -rf ~/.config/papyrus

Flatpak:

flatpak uninstall io.github.PSGtatitos.papyrus

Contributing

Pull requests are welcome. For major changes, open an issue first.

Built with assistance from: Claude (Anthropic) was used as a coding assistant during development.

License

GPL-3.0 — same license as mpvpaper.