it started with a zelda wallpaper

In September 2022 I came across Matt Vince's Zelda Wind Waker wallpaper pack: one island, painted at four times of day. Beautiful. Four wallpapers that only make sense if they change with the day, and nothing on my Windows laptop could do that. There was a HEIC version available, but those only work natively on macOS. So I spent a weekend putting together something that could work on my laptop.

a weekend version

I remember sitting on the top bunk of my hostel room and writing the "wallmap" spec and its parser by hand. v1 was just a Python script, plus a JSON "wallmap" per wallpack that said which image went with which hour.

Setting it up meant six manual steps in Windows Task Scheduler: run the script at startup, then again every five minutes, forever, and untick "start the task only if the computer is on AC power", etc. I wanted to implement this for macOS and Linux too, but never got around to it, as I never needed it.

In any case, v1 served my purpose. Every five minutes, for the better part of two years, my laptop started a Python interpreter to check whether it was time for a new picture. And every time I opened my laptop and saw the Zelda wallpaper change on its own, it made me so happy.

starting over, twice

v1, good as it was, still had a few "quirks". For example, I could not reasonably share it with my friends, because of the setup steps required. And even if I did, it used to literally flash a cmd prompt window for a fraction of a second, and it could get annoying for some people.

So in January 2025 I deleted everything and rebuilt it properly, still in Python: wallpacks that find and validate themselves, schedules that can say sunrise+1h30m instead of a fixed hour, and a solar calculator so that sunrise means your sunrise. It became a CLI tool on PyPI, so installation was as simple as pip install wallpy. That was v2, and it reached 2.25.0.

v2 still had its own caveats. To use wallpy, you needed Python installed, and there was no easy way to share, download, or make your own wallpacks.

In October 2026 I started over again, this time in Go, and finished the gallery alongside it. I liked the idea of browsing a community curated gallery of dynamic wallpacks, and easily downloading them using the CLI. This is where it stands as of v3!

The Deku Tree wallpack page in a browser, with a terminal in front
Both halves: a wallpack's page in the gallery, and the CLI showing the same wallpack.

small things I love

  • The gallery, in the terminal. wallpy browse lists every wallpack in the gallery and draws a preview of each one right in the terminal: real pixels where the terminal can show images, coloured half blocks everywhere else. Press enter and it's your wallpaper.
  • One command. wallpy use <pack> downloads a wallpack, switches to it, sets the wallpaper and starts the background agent.
  • It changes right at sunset. v1 checked every five minutes. The agent now sleeps until the next change and wakes on time.
  • It doesn't fight you. Set a wallpaper by hand and Wallpy leaves it alone until the next scheduled change.
  • "bangalore" is in India. The online geocoder matched it to a town in Pakistan, not Bengaluru. City search is offline now: every city of 15,000+ people, built into the app. It's instant, and nothing about where you are leaves your machine.
wallpy browse in a terminal over the Desert Sands wallpaper
wallpy browse: the gallery in a terminal. Previews use Kitty graphics where the terminal supports them, and half blocks everywhere else.

one spec, two programs

The gallery is a Next.js site on Supabase, with the images on Cloudflare R2. Anyone can make a wallpack there in the browser, and every wallpack is reviewed before it's listed.

The Wallpy gallery: a search bar, category filters and a grid of wallpacks
The gallery at wallpy.siphyshu.me.

The site and the CLI are separate programs in different languages, so the wallpack format is written down as a spec with 23 test vectors: a schedule, a time and a place go in, the image that should show comes out. Both have to pass them. If the site accepts a wallpack, the CLI has to show exactly the image the spec says it shows.

And the Zelda Wind Waker wallpack that started all this is in the gallery now.

The Wind Waker island as one picture cut into dawn, morning, dusk and night
Zelda Wind Waker by Matt Vince: one island, through four of its sixteen images.

try it

The gallery has every wallpack, with its schedule and a preview of each image. If one catches your eye, the docs get Wallpy onto your machine in one command. And if you have a set of wallpapers that only make sense together, sign in and make a wallpack of your own!