PiClock: a Raspberry Pi wall clock, now a Python 2 archive you can still run

What this repository is for, stated plainly in the README

The first line of the project documentation is the most important thing to know before anything else: this repository is here to keep older PiClocks running. If you have one built years ago, or a Pi and an operating system you would rather not change, this is the version for you.

That framing changes what the project is. PiClock is a Fancy Clock built around a monitor and a Raspberry Pi, and the description of the underlying software is precise about the stack: it is Python 2 and PyQt4, and it runs up through Raspberry Pi OS Buster, which is Debian 10, on a Pi 1 through a Pi 4.

The limitation is stated in the same paragraph and it is not negotiable within this codebase. PyQt4 was dropped from Debian after Buster, so Bullseye and newer will not run it, and the documentation is blunt that there is no way around that short of the rewrite below.

So there is no ambiguity here about what you are picking up. This is a preservation branch, maintained so that hardware already in the field keeps working, not an actively developed clock. The repository topics reflect the same thing, listing pyqt4 and python2 alongside clock, weather, weather-station, radar and raspberry-pi.

The licence is MIT, the default branch is master, and there are no GitHub releases, so the history is the commit log rather than a version list.

Why the author redirects you to a fork for new builds

The next paragraph is the one to read if you are considering building one. If you are building a new PiClock, or you are already on Bullseye or newer, the README suggests SerBrynden's fork, which is Python 3 and PyQt5, is kept current, and is where the active development is.

That recommendation carries an implication for anyone evaluating this repository as a dependency. The upstream author is not asking for contributions here, and the reason is structural rather than personal. A Python 2 and PyQt4 application cannot be made to run on a current Raspberry Pi OS without porting the GUI toolkit, and porting a PyQt4 application to PyQt5 is a rewrite of the whole UI layer, not an upgrade.

The repository layout supports the reading that this is a frozen application with an occasional fix. There is a PiClock.desktop file for a desktop entry, a startup.sh and a switcher.sh for launching and switching views, an update.py, and then separate directories for the hardware pieces: Button/ for the GPIO buttons, IR/ for the infrared remote, Leds/ for the LED option and Temperature/ for the temperature sensor. There is a gimp/ directory for artwork and a Contributed/ directory for community additions, plus Documentation/ holding the guides.

The interesting detail is that Clock/ is a directory rather than a single script, which tells you the clock rendering is split into modules, and that the optional hardware features are cleanly separated so a build with none of them is a normal configuration rather than a stripped-down one.

Weather moved to Open-Meteo, radar moved to LibreWXR

This is the practical part of running an old install, because the upstream services the code was written against have mostly gone away.

The documentation says a lot of the weather and radar services this was built on have since gone away or been restricted. Radar now comes from LibreWXR, with rainviewer still selectable in Config.py via the userainviewer setting. Anything older than Buster will also need certificate authorities added before those services will answer it, and the install guide covers that.

The certificate point is worth dwelling on, because it is the kind of failure that looks like a network problem. A Buster-era or older image ships with a root certificate bundle that predates the CA that signs the current endpoints, so the HTTPS request fails, and the symptom on a clock is a blank panel where the radar should be rather than an error message. Adding the certificate authorities is a documented step in the install guide, which is exactly the kind of detail that makes an old install workable.

Weather comes from Open-Meteo unless you put an api key in ApiKeys.py, so no weather signup is needed. That is a change from the original design, where the weather provider was a signed-up service, and it removes a step that used to block a fresh install. The one remaining key requirement is a Mapbox or Google Maps key for the maps under the radar.

So the current setup needs one key for the maps and none for the weather, with the provider switch living in Config.py and the key in ApiKeys.py.

The four documentation paths, and the hardware you do not need

The project ships four documents and each one answers a different question, so picking the right one saves a lot of time.

For a new build on an older Pi, the README suggests starting with the overview document. For a desktop use, meaning running the clock on a desktop machine rather than on a Pi, there is a separate install guide for the clock only. Then the main install guide, and the hardware guide which you can jump to at any point.

The hardware point deserves emphasis because it is the most common reason people assume a project like this is expensive. All of the extra hardware, which the documentation lists as the IR Remote, GPIO buttons, Temperature and LEDs, is optional, so you can go straight to the install guide. The minimal build is a Raspberry Pi, a monitor and the software.

That is what makes the project interesting as a design exercise rather than a shopping project. A Pi and an extra monitor, the origin story makes clear, were on hand, and the author had just taken down an analog clock from the living room wall. The plan was a radio synchronised analog clock so the time would be accurate, and instead a PiClock was born.

The project grew out of a way to waste a Saturday afternoon, and the history and evolution of it are chronicled on the author's blog. That origin also explains the aesthetic, which is the fancy part of Fancy Clock, with a radar map of precipitation and a weather panel.

What you are signing up for with a legacy Python 2 install

There are practical consequences to running this branch that are worth planning for.

The first is the interpreter. Python 2 reached its end of life, and an operating system that still installs it for you is one you are deliberately not upgrading. The README frames this as a feature for a device you would rather not change, and that framing is fair, but the trade is that you also stop receiving operating system security updates unless the device is isolated from the network in some other way.

The second is the toolkit. PyQt4 is not in current Debian, so there is no path to getting this running on Bullseye or Bookworm without the rewrite. The clock's own code being Python 2 is the smaller half of that problem; the missing toolkit is the blocking half.

The third is the third-party services, and this is the part most people underestimate. The radar and weather data are fetched over the network from services that have changed, moved or added restrictions since the code was written. The current tree has been adjusted to work with the present state of those services, but the direction of travel is clear. A clock on a wall that quietly stops updating its weather because a provider changed its API or its certificate is a failure mode with no local symptom, and it needs a person to look at it.

None of this makes the project bad. It makes it a specific thing: a working, pleasant clock for a Pi you already own, kept alive for the hardware in the field, with an explicit pointer to the maintained fork for anyone building today.

Editorial conclusion

Adopt this PiClock repository if you have an existing PiClock on Buster-era Raspberry Pi OS and want to keep it running, since that is exactly what this branch exists for. Do not start a new build on it, because PyQt4 was dropped from Debian after Buster and the author points to a Python 3 fork for new installations. Before you commit, confirm your SD card is still on Buster or older, and note the last push was on 2026-08-28.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. n0bel/PiClock on GitHub
4. README