Live (video) wallpapers for Linux, Windows and macOS. Built first for Linux Mint Cinnamon, with general Ubuntu/Mint compatibility, and now ported to Windows and macOS as well.
Think "Wallpaper Engine" / "Lively Wallpaper": GUI-only, and engineered to cost effectively nothing in CPU/RAM while idle.
Open the app, import an MP4 (or download one from the built-in online library), click Set as wallpaper, and it plays full-screen as your real desktop background. It pauses automatically when a fullscreen app is focused, the screen is locked, the battery is low, or a window covers the desktop, so it costs next to nothing when you can't see it. It has a gallery library with collections, an Online tab that searches several wallpaper sites at once, a download manager, and a tray widget.
| Platform | How |
|---|---|
| Linux (X11) | .deb, .rpm, Flatpak, or from source |
| Linux (Wayland: Hyprland, Sway, …) | wlr-layer-shell background layer |
| Windows 10/11 | setup .exe or .msi; the window sits behind the desktop icons (including the Windows 11 24H2 layout) |
| macOS 15+ | .dmg; desktop-level window on the main display |
- Library: import MP4, WebM, MKV, MOV, GIF and still images; collections you make yourself plus automatic ones (by topic, source, favorites and tags); favorites, tags and sorting; duplicate imports are recognised.
- Sharing: send one wallpaper, a selection, a collection or your whole library to a friend as a short share code or a
.paperloomsharefile; they import it, see a preview, pick what they want and the wallpapers download from the same sites into a collection of their choice. Nothing from your computer is sent, only where each wallpaper comes from. Select several wallpapers with the Select button; open a share file by double-clicking it, dropping it on the window or choosing Import a share. - Cheap to run: imports are re-encoded in a low-priority background step only when that makes them cheaper to play (formats a graphics card can't decode, more pixels than your screen, more than 30 fps). Hardware decoding, a small decode cache, no audio decoding while muted, and a guard that lowers quality by itself if a wallpaper keeps the CPU busy.
- Online: searches several sources at once, hides wallpapers you already have, opens a detail pop-up with a streaming preview, and takes pasted links.
- Rotation and schedule: change the wallpaper on an interval or by a weekly schedule, even with the window closed.
- Pauses by itself: fullscreen app, locked screen, low battery, covered desktop, chosen apps, or no input for a while.
- Control: tray menu, global keyboard shortcuts, and
paperloom-gui next|pause|resume|mute|stop|status|set <name>from a terminal. - Themes: Settings → Appearance changes how Paperloom's own window looks: colours for light and dark, fonts, corner shapes, size, where the navigation sits (left, right, top or bottom), a backdrop, picture layers (animated ones too) and the look of single parts such as buttons and pop-ups. Pick a built-in theme, download one from the online library, import one, or edit one in the app.
- AI agents (MCP): switch MCP on (Settings → MCP) and an agent on your computer (Claude Code, OpenCode, Cursor, a browser agent, or anything that can make a web request) can do what the window does: set and change the wallpaper, import files and links, manage collections, search and download, place widgets. It runs only while switched on.
- Updates: inside the app, any release (older ones too) can be downloaded and installed.
- Developer mode: Settings → Advanced adds a Developers page with live engine status, copyable diagnostics, logs, test actions, and Run all tests, which checks everything on a computer and writes one report.
Contributing or picking this up as an agent? Start at AGENTS.md.
Download from the Releases page:
| System | File |
|---|---|
| Windows | …-windows-x86_64-setup.exe (or the .msi for managed installs) |
| macOS, Apple Silicon / Intel | …-macos-aarch64.dmg / …-macos-x86_64.dmg |
| Ubuntu, Linux Mint 22+, Debian | …-linux-x86_64.deb |
| Fedora, openSUSE | …-linux-x86_64.rpm |
| Any Linux | …-linux-x86_64.flatpak (flatpak install paperloom-….flatpak) |
Once installed, Paperloom keeps itself current. Settings → Updates checks GitHub for new releases, downloads the right installer for your system (resumable, SHA-256 verified) and opens it. You can also skip a version there. Flatpak installs are updated by Flatpak instead.
This gets you updates automatically with your normal system updates (Update Manager / sudo apt upgrade):
sudo curl -fsSLo /usr/share/keyrings/paperloom.asc https://theamanullahdev.github.io/paperloom/apt/paperloom.asc
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/paperloom.asc] https://theamanullahdev.github.io/paperloom/apt stable main" | sudo tee /etc/apt/sources.list.d/paperloom.list
sudo apt update && sudo apt install paperloom
If you already installed a .deb by hand, run the same three lines: apt takes over that install and keeps it updated from then on. The repository is published by .github/workflows/apt-repo.yml on every release and signed with the APT_GPG_PRIVATE_KEY secret (setup is described at the top of that file).
Easiest, any distro: Flatpak. Download …-linux-x86_64.flatpak from the Releases page, then:
flatpak install --user ./paperloom-*-linux-x86_64.flatpak
flatpak run io.github.theamanullahdev.Paperloom
(Needs flatpak installed, e.g. sudo pacman -S flatpak. Flatpak installs are updated through Flatpak.)
Arch / Manjaro / EndeavourOS, from source with pacman tooling. There's a PKGBUILD in packaging/arch:
sudo pacman -S --needed base-devel git
git clone https://github.com/theamanullahdev/paperloom && cd paperloom/packaging/arch
makepkg -si
Any distro, build from source. You need Rust (rustup or your distro's cargo), pkg-config, and mpv's library with headers, plus ffmpeg at runtime (for hover previews):
| Distro | Install the build/run dependencies |
|---|---|
| Arch and derivatives | sudo pacman -S --needed rust mpv ffmpeg pkgconf libxkbcommon wayland vulkan-icd-loader |
| Debian, Ubuntu, Mint | sudo apt install cargo pkg-config libmpv-dev ffmpeg libxkbcommon-dev |
| Fedora | sudo dnf install cargo pkgconf mpv-devel ffmpeg-free libxkbcommon-devel |
| openSUSE | sudo zypper install cargo pkgconf libmpv-devel ffmpeg libxkbcommon-devel |
git clone https://github.com/theamanullahdev/paperloom && cd paperloom
cargo build --release
sudo install -Dm755 target/release/paperloom-gui target/release/paperloom-engine target/release/paperloom-widgets target/release/paperloom-mcp -t /usr/local/bin
paperloom-gui
Both programs must be installed in the same folder (the GUI starts the engine from next to itself).
Hyprland, Sway and other wlroots compositors (Wayland). Paperloom draws the wallpaper on a wlr-layer-shell background layer, which these compositors provide. Wayland has no portable way to see fullscreen or covering windows, so there the wallpaper pauses for screen lock and low battery. The tray icon needs a bar with StatusNotifier support (for Waybar, enable the tray module); otherwise use the app window. Found a problem? Open an issue.
Software centers: Linux Mint's Software Manager and GNOME Software list apps from your enabled sources. After adding the apt repository above, paperloom is searchable in Mint's Software Manager like any other package.
Settings → Updates in the app downloads the newest installer and opens it in your system's package installer, where you confirm. A .deb/.rpm downloaded by hand doesn't update in the background. To update one from a terminal:
curl -fsSL https://api.github.com/repos/theamanullahdev/paperloom/releases/latest \
| grep -o 'https://[^"]*linux-x86_64\.deb' | head -n1 | xargs curl -fL -o /tmp/paperloom.deb \
&& sudo apt install /tmp/paperloom.deb
On Fedora, replace \.deb with \.rpm and the last line with sudo dnf install /tmp/paperloom.rpm. Restart Paperloom (and stop/start the wallpaper) afterwards.
First launch on Windows and macOS:
- Windows: SmartScreen shows "Windows protected your PC". Click More info → Run anyway.
- macOS: open System Settings → Privacy & Security and click Open Anyway next to Paperloom, or run
xattr -dr com.apple.quarantine /Applications/Paperloom.app.
Linux requirements: the .deb/.rpm need the system's libmpv (libmpv2 on Ubuntu 24.04 / Mint 22; mpv-libs on Fedora), which the package manager installs automatically. Ubuntu 22.04 / Mint 21 ship an mpv that's too old (client API v1).
Settings → Appearance is one workspace: themes on the left, the chosen one on the right.
- On this computer lists the built-in themes and every theme you downloaded, imported or made. Download is the online library; a downloaded theme appears in On this computer.
- Import a theme takes a
.paperloomthemefile or atheme.toml; Import a folder takes a theme folder. Save as a file turns one of your themes into a.paperloomthemeto pass on. - Edit opens the theme's file as a form: colour fields, sliders, choices, picture layers, and a Raw file tab with the text itself. Editing a built-in theme edits a copy. Preview shows the draft on the whole window for ten seconds.
- A theme that moves things asks Keep this theme? and goes back by itself after ten seconds.
paperloom-gui --default-themestarts with Paperloom's own look.
A theme is a folder with a theme.toml and, if it wants, fonts/ and images/. Everything in the file is optional; what a theme leaves out keeps Paperloom's default. The format is described in crates/paperloom-theme/src/schema.rs, and an AI agent can read it (get_theme_schema), write a theme, check it and apply it through MCP.
To add a theme to the online library: make themes/<id>/theme.toml (plus a preview.png thumbnail of at most 300 KB), run python3 scripts/build-themes-index.py, and commit.
Open Settings → MCP and press Turn on MCP. The page then shows what to copy for your agent:
| Agent | What you copy |
|---|---|
| Any agent on this computer | a ready prompt with the address, the token and every way to connect |
| Claude Code | one claude mcp add … command |
| OpenCode | a block for opencode.json |
| Cursor, Claude Desktop, VS Code and other MCP clients | an mcpServers block (HTTP, or a program to start) |
| A browser agent | a link to a page with a form for every action |
Then ask in your own words: "download this video and set it as my wallpaper", "put my rainy wallpapers in a collection and rotate them every 30 minutes", "add a clock to the top right corner". If Paperloom can't download from a link itself, the agent downloads the file and imports it.
How it is built:
paperloom-mcpis its own small program. It starts when you press Turn on MCP, never by itself or at login, and ends when you turn it off (or after 12 hours without a request). While it is on, the top bar shows MCP on on every page.- It listens on
127.0.0.1only, and every request needs the token shown on the page. New token replaces it. - Three switches decide what an agent may do: Allow changes (on), Allow removing (off), Allow changing settings (off). Removing always needs an explicit confirmation from the agent as well.
- One set of tools, reachable as MCP over HTTP (
/mcp), MCP over stdin/stdout (paperloom-mcp), plain JSON (/tools,/call/<tool>), a web page (/) and a shell command (paperloom-mcp call <tool> '{…}').paperloom-mcp toolslists them.
A release is started on purpose from the Actions tab and becomes a new GitHub Release, built by .github/workflows/release.yml:
- Version: worked out from the commit messages since the last release (
scripts/next-version.sh):feat: …→ minor (0.2.0)fix: …or anything else → patch (0.1.1)feat!: …orBREAKING CHANGE→ major (minor while the version is still 0.x)
- Test: clippy and the test suite.
- Build every installer:
.deb,.rpm,.flatpak,.msi, setup.exe, and both.dmgs, each on its real platform (package.yml). - Publish, only if all of that passed: commit the version bump, tag
vX.Y.Z, and create the Release. It carries every installer,SHA256SUMS.txt, and notes listing the commits.
Pushing commits never releases. To cut a release, open Actions → Release → Run workflow (or gh workflow run release.yml) and leave the bump on auto or pick patch, minor or major.
CI (ci.yml) runs on every push and PR. It builds all the same installers without publishing them, and they're downloadable from that run's Artifacts section.
If you ever add branch protection to main, allow the github-actions[bot] to push (or the release's version-bump commit will only live on the tag; releases still work).
The Flathub submission files (manifest, pinned sources, screenshots and the steps) are in flathub/.
sudo apt install libmpv-dev ffmpeg # libmpv for the engine, ffmpeg for gallery previews
cargo build
cargo run -p paperloom-gui # Import a wallpaper, click "Set as wallpaper" — done
The GUI starts paperloom-engine itself the first time you set a wallpaper. To test the engine directly, without the GUI:
cargo run -p paperloom-engine -- /path/to/loop.mp4 # Ctrl+C to stop
The engine links the system's mpv client library through the libmpv2 crate. It's not the plain libmpv crate; AGENTS.md explains why. Packages:
cargo install cargo-deb cargo-generate-rpm
cargo build --release --workspace
cargo deb -p paperloom-gui --no-build # target/debian/*.deb
cargo generate-rpm -p crates/paperloom-gui # target/generate-rpm/*.rpm
Run these in an MSVC developer PowerShell, with gh and 7z installed:
pwsh packaging/windows/fetch-mpv.ps1 -Out C:\mpv # libmpv-2.dll, ffmpeg.exe, mpv.lib
$env:RUSTFLAGS = "-L native=C:\mpv"
cargo build --release --workspace
Copy libmpv-2.dll and ffmpeg.exe next to the built executables. The installers are built with WiX 5 (packaging/windows/paperloom.wxs) and Inno Setup 6 (paperloom.iss); see package.yml for the exact commands.
brew install mpv ffmpeg dylibbundler
RUSTFLAGS="-L $(brew --prefix)/lib" cargo build --release --workspace
packaging/macos/build-dmg.sh 0.1.0 target/release dist # bundles every dylib into Paperloom.app