Inkycal reads settings.json and paints an e-paper screen on a Raspberry Pi

The screen is the product, not a browser tab

Inkycal exists because e-paper and a normal display behave differently. An e-paper panel holds its image with no power, refreshes slowly, and is read from across a room. That rules out the usual approach of leaving a browser full screen on a cheap HDMI stick.

What Inkycal is instead is a Python program that composes an image and hands it to the panel. It runs on a Raspberry Pi, draws the layout, and pushes the result to the display. The list of what it can show is short and concrete: calendars and schedules, weather forecasts, tasks and reminders, photos and slideshows, and custom Python modules you write yourself.

The stated hardware floor is a Raspberry Pi Zero W, a board with wireless built in. That constraint matters because e-paper dashboards are the kind of project people put in a hallway with no keyboard nearby. Anything you build has to run unattended after one setup session.

The repository records its primary language as C, which is unusual for a Python dashboard. It points at the native display libraries underneath rather than at the module code, and the application layer is Python 3, built around a package named inkycal.

The other thing to understand is the split the README insists on. InkyCal v3 is the assembled hardware product with a customer setup path. Inkycal is the software in this repository that you install yourself. If you bought a device, the documentation you want is the customer hub, not this source tree.

requirements.txt is the honest module list

The dependency file is more informative than the feature list, so read it as documentation.

Calendar work is handled by icalendar, recurring-ical-events and python-dateutil, with arrow and tzlocal for time handling. Those five packages explain what the calendar and schedule modules can do, including recurring events and timezone-correct rendering, which is the part people get wrong in home-grown dashboards.

Feeds come in through feedparser, and stock quotes through yfinance, so market data is treated as a displayable module rather than an add-on. Tasks integrate with Todoist through todoist_api_python. A QR code generator, segno, is in the list, which tells you the project expects identifiers such as Wi-Fi credentials or check-in codes to be scannable off the panel.

Rendering is Pillow and numpy, with matplotlib available for charting. selenium is present, which is unusual in this category and points at module authors being able to scrape a value that has no API. xkcd is included as a joke module.

Two entries deserve a second look. yfinance and selenium both depend on third-party services behaving a certain way, and neither is a stable contract. A module built on them is the part of your dashboard most likely to break silently. requests, certifi and python-dotenv round out the network and configuration layer.

Versions are pinned with compatible-release operators, for example pillow~=12.3.0, so you get patch updates but not major jumps.

settings.json is the contract between the Web UI and the Pi

Configuration is the part of an e-paper project that usually turns into a mess of scattered files. Inkycal takes a different approach: one JSON file called settings.json, generated in the browser through a Web UI generator hosted at inkycal.aceinnolab.com/ui, then copied to the machine that drives the panel.

The quick start in the README is four steps: pick your display model, create settings.json in the Web UI, follow the installation guide in the docs, then run Inkycal on the Pi. Step one is the one that decides whether anything works later. E-paper panels differ in resolution, driver and refresh behaviour, and the display model you choose is what the rest of the configuration is measured against.

The directory layout supports the same split. inkycal/ holds the package itself, including templates, static files and assets that are shipped as package data, and inky_run.py and inky_webui.py sit at the top level as the entry points for running a dashboard and for the settings interface. MANIFEST.in and include-package-data are there so a self-contained panel configuration survives packaging, which matters if you are assembling an image rather than running from a clone.

There is also a local Web UI, documented separately, for settings and display tools once the device is running. So configuration exists in two places: the hosted generator before deployment, and the local interface afterwards. If you are building several panels, you will be editing the same JSON repeatedly.

Installation is a docs page, an installer script and an SD image

The README deliberately contains no shell commands, and points you at the installation guide under aceinnolab.github.io/Inkycal/installation. That is where the real steps live, so treat the repository as the source rather than the procedure.

What the repository does show is how the pieces are split. installer.py sits at the top level as an install path inside the project, and alongside it are apt_packages.txt, raspberry_os_requirements.txt, dev_requirements.txt and requirements.txt. The separation is the useful detail: some dependencies are system packages installed with apt, some are Raspberry Pi OS specific, and only one file is the ordinary Python set. A setup that skips the first two will fail on hardware access even with every pip requirement satisfied.

There is a devcontainer directory and a tests directory, so the project can be worked on away from the Pi. The package metadata is plain and gives you the version and dependency floor directly:

[project]
name = "inkycal"
description = "InkyCal – e-paper calendar/dashboard for Raspberry Pi"
requires-python = ">=3.9"
license = { text = "GPL-3.0-only" }

Note the floor and the classifiers disagree slightly in spirit: requires-python is 3.9, while the README badge advertises 3.11 through 3.13. Sponsors receive InkycalOS-Lite, a pre-built SD card image with everything configured, which is the fastest route and the one most likely to leave you dependent on an image you cannot easily inspect.

GPL-3.0-only and a Beta classifier, on a schedule that moves fast

Two pieces of metadata tell you what you are adopting.

The licence is GPL-3.0-only, spelled out that way in pyproject.toml and confirmed by the LICENSE file at the top level. Only matters here: the project is not offered under an alternative licence, so if you intend to ship Inkycal inside a closed product, the copyleft terms apply to your combined work. That is a licensing question rather than a technical one, and worth raising with whoever owns your compliance, not with the maintainers.

The second marker is the Development Status:: 4 - Beta classifier. The project says so itself, which is more useful than inferring it. Combined with a Raspberry Pi dependency and e-paper drivers, that means you should expect to fix things on hardware you own rather than file a ticket and wait.

Release history shows a project still finding its cadence. The most recent release is v2026.07.01, published on 2026-06-30, and the last push was on 2026-09-12, so commits have continued after that tag. Before v2026.07.01 the naming was inconsistent: a 2025-12-15 release carries a date instead of a version number, and v2.0.4 dates from 2024-07-09. Pin by tag when reproducibility matters and read the release notes for v2026.07.01 to see whether an upgrade changes configuration keys.

The maintenance statement in the README is honest about the reason: the project is maintained in spare time.

Where Inkycal is the wrong tool

Three cases come to mind.

If you need a screen that changes within seconds, e-paper is the wrong display regardless of software. The refresh behaviour of the panel is the constraint, not the renderer.

If your dashboard needs a keyboard, a scrolling list or anything you interact with, this is the wrong category of device. A local Web UI is available for settings, but that is a configuration surface, not an interactive front end for the display itself.

If you want the ready-made product and customer setup, InkyCal v3 is a different route from installing this software.

There is also a scale limit worth stating plainly. Each panel gets its own settings.json, its own Pi and its own place in your network. If you want one calendar shown in three rooms, you are running three installations unless the module layer handles distribution, and the visible documentation does not describe a multi-panel mode.

Where it does fit, the fit is good: a hallway calendar that survives a power cut, shows a QR code for joining the wireless, and refreshes on a schedule you set once.

Editorial conclusion

Adopt Inkycal if you want a wall display that refreshes without a browser and can survive being left unplugged, and you are comfortable writing or reading a JSON settings file; skip it if you want the ready-made product and customer setup, because the open-source project and InkyCal v3 are separate things. Verify first that your exact e-paper panel is in the display model list offered by the Web UI generator, since the README makes picking the display model step one of the quick start.

Frequently asked questions

Official sources

1. aceinnolab/Inkycal on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases