For Hyprland & Caelestia

Your wallpapers,
actually organized.

LiveWall is a fast, self-hosted wallpaper library for Hyprland with tags, favorites, search, and duplicate detection for both static images and real animated wallpapers, applied instantly from a global keybind.

Get LiveWall View on GitHub
Python + Textual uv-managed AGPL-3.0-or-later No cloud, ever
▶ mp4
▶ webm
Everything a library needs

The features caelestia-aw doesn't have

caelestia-aw already renders wallpapers beautifully. LiveWall handles the part underneath, actually managing a growing collection of them.

🏷️

Tags

Organize your library by mood, source, or resolution, then filter and browse by tag from the CLI, GUI, or picker.

★

Favorites

Star the wallpapers you keep coming back to and surface them first, everywhere in the app.

🔍

Search

Instant fuzzy search across names and tags finds the right wallpaper in a library of hundreds without scrolling.

📋

Duplicate detection

LiveWall flags near-identical files on import so your library doesn't quietly fill up with copies.

🎬

Real animated wallpapers

Genuine mp4/webm/mkv video decode via an mpv-based backend means actual video playback, not GIF hacks.

⚡

Quick picker

livewall picker, bound to Super+Shift+B, is a fast, tag- and favorite-aware picker for switching wallpapers without leaving your workflow.

🔋

Battery-saver mode

Animated wallpaper playback pauses based on real battery percentage, not just AC power state, so it actually saves power on a laptop.

🔧

Boot-fix service

A background fix self-corrects a known caelestia-aw startup glitch automatically after every login. Install it once, forget about it.

LiveWall tags · favorites · search · picker
▼ applies wallpapers through
caelestia-aw native rendering
▼ patches into
Caelestia Quickshell shell Hyprland

Built on caelestia-aw, not around it

caelestia-aw is a patch that adds native animated-wallpaper rendering to the Caelestia Quickshell shell. It's the engine, and LiveWall doesn't replace it or fight with it.

What caelestia-aw gets you: fast, native video rendering of your wallpaper, directly in the shell.

What it doesn't give you is a way to actually manage a library. That's the whole point of LiveWall:

  • A real library: every wallpaper tracked, tagged, and searchable, not just a folder of files.
  • A TUI browser, livewall gui, for scrolling, tagging, and favoriting visually.
  • A quick picker, livewall picker, bound to a global keybind, for switching without breaking flow.
  • One command to apply: livewall apply <name> switches the live wallpaper by library name.
Get started

Install in under a minute

Python 3, managed with uv. Installed editable, so pulling the repo is all you ever need to update.

install.sh 
# clone the repo
git clone https://github.com/rusty-workshop/livewall.git
cd livewall

# install with uv, editable, so updates apply instantly on pull
uv tool install --editable .

# the CLI, the TUI library browser, and the quick picker
livewall               # manage your library from the shell
livewall gui           # full Textual library browser
livewall picker        # fast tag/favorite-aware picker (bind to Super+Shift+B)

# switch the live wallpaper by name
livewall apply sunset-ridge
Requires caelestia-aw already patched into your Caelestia/Hyprland setup. Full setup notes live in the repo README.

No cloud. No subscriptions. Just your wallpapers.

LiveWall is local file management for a personal library, not a wallpaper-download service. Everything stays on your machine.

Star it on GitHub