wallpick

a small wallpaper picker for wayland compositors, built on quickshell. a strip of thumbnails, a big preview, and the wallpaper changes as you scroll. it applies through whatever you already use: hyprpaper, awww, swww, swaybg, caelestia, or any command you give it.

install

one line, it asks about your backend and wallpaper folder and puts everything in ~/.local/share/wallpick:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/iamanuclearwarhead/wallpick/main/install.sh)"

or from a clone:

git clone https://github.com/iamanuclearwarhead/wallpick
cd wallpick && ./install.sh

arch users can take the aur package instead:

paru -S wallpick-git

the installer never touches your compositor config. it prints the keybind line for you to add. ./install.sh --uninstall removes it again.

dependencies: quickshell, qt6-declarative, jq, file, util-linux. optional: ffmpeg for video wallpaper thumbnails.

use

command	what it does
wallpick	open the picker, or close it if it is open
wallpick set <file> [screen]	apply a wallpaper without the picker
wallpick restore	re-apply the last wallpaper, for autostart
wallpick backend [name]	show or set the backend
wallpick dir [path]	show or set the wallpaper folder
wallpick status	what is running, configured and installed

in the picker: scroll, arrow keys, h and l, or a and d move along the strip, home and end jump, clicking a thumbnail selects it. the selected wallpaper is applied as you go, and enter, space, escape or a click outside closes the picker. set applyOnSelect to false if you would rather enter applies and escape cancels. video files show a still frame and are applied as that frame on daemons that cannot play video.

keybinds

hyprland:

bind = SUPER, W, exec, wallpick
exec-once = wallpick restore

hyprland with the lua config:

hl.bind("SUPER + W", hl.dsp.exec_cmd("wallpick"))
hl.on("hyprland.start", function() hl.exec_cmd("wallpick restore") end)

sway:

bindsym $mod+w exec wallpick
exec wallpick restore

niri:

Mod+W { spawn "wallpick"; }
spawn-at-startup "wallpick" "restore"

to blur what is behind the picker on hyprland, add a layer rule for its wallpick namespace:

layerrule = blur, wallpick

hl.layer_rule({ match = { namespace = "wallpick" }, animation = "fade", blur = true })

restore only matters for daemons that forget their wallpaper on logout. caelestia and hyprpaper with a config file remember on their own.

backends

auto picks the first one it finds running, then the first one installed. wallpick backend <name> pins one.

backend	how it applies	per monitor
hyprpaper	hyprctl hyprpaper wallpaper "<monitor>,<path>,<fit>", with the preload dance on versions before 0.8, starts the daemon if needed	yes
awww	awww img --outputs <monitor> --transition-type <t> <path>, starts awww-daemon if needed	yes
swww	same as awww with the older binary names	yes
swaybg	one swaybg process per monitor, the old one is killed after the new one is up	yes
caelestia	caelestia wallpaper -f <path>, so caelestia also regenerates its colour scheme	no, caelestia applies everywhere
command	your template, with {path}, {screen} and {transition} filled in	if the template uses {screen}

videos are shown in the picker and, for daemons that cannot play them, applied as a still frame.

config

~/.config/wallpick/config.json, every key optional:

key	default	meaning
wallpaperDir	~/Pictures/Wallpapers	folder the strip shows
backend	auto	one of auto, hyprpaper, awww, swww, swaybg, caelestia, command
command		template for the command backend
screen	all	monitor to apply to, or all
transition	fade	swww and awww transition name
fit	cover	cover, contain, fill, tile or center, for hyprpaper and swaybg
historySize	200	entries kept in the history file
applyOnSelect	true	apply while scrolling, enter and escape both just close
sort	name	name, or modified for newest first
thumbHeight	150	thumbnail height in pixels
previewHeight	0.55	preview height as a fraction of the screen
videoThumbnails	true	list video files too, needs ffmpeg
font	sans-serif	any installed family
borderRadius	12	corner radius
colors		object with bg, fg, accent, backdrop, hex with optional alpha

the picker follows the file while it is open. state lives in ~/.local/state/wallpick, video frames and history in ~/.cache/wallpick.

credits

the idea of a wallpaper carousel as a keybind came from the one in serpantinum. wallpick 0.1 was an extraction of that picker; 0.2 is a rewrite from scratch with none of that code left.

license

gpl-3.0-or-later. the 0.1 releases were agpl-3.0 because they contained serpantinum code.