pylendar

A Python port of the classic BSD calendar(1) reminder tool. You keep a plain-text file of dates, and pylendar tells you which ones are coming up.

$ pylendar -w -W30
Sun Jun 21*	Summer solstice ☀️
Wed Jul  1	Canada Day 🍁
Sat Jul  4	US Independence Day 🦅
Tue Jul 14	World Emoji Day 🙌

Why it exists

The BSD calendar program has been around since Version 7 AT&T UNIX, and the idea behind it is wonderfully simple: a text file where every line is a date and a description, and the program prints whatever falls in the next few days. No database, no sync service, no account to sign up for. Just a file you can grep, diff, and keep in version control alongside everything else.

That simplicity is why it's still worth using. The catch is that the BSD variants have drifted apart over the decades. FreeBSD, macOS, OpenBSD, NetBSD, and Debian each grew their own set of date formats and flags, and none of them are easy to get running on many modern Linux systems.

pylendar brings the idea back as a single, lightweight Python program that:

• reads them all. It understands the date formats from every major BSD variant, so existing calendar files just work.
• adds a few niceties. ISO 8601 dates (2026-02-17), automatic age calculation (Pat turns [1990] becomes Pat turns 36), and weekday-relative dates like Sun<Dec 25 (the last Sunday before Christmas).
• gets the astronomy right. Moon phases, equinoxes, and solstices are pinned down precisely with the astronomy-engine library. Easter and the Chinese New Year land on the right day every year, too.
• speaks Unicode. Full UTF-8 and emoji support ⭐, so your calendar files read the same everywhere.
• runs anywhere Python does, and installs in a single command.

pylendar intentionally omits the superuser email mode. On BSD, calendar -a processes every user's calendar file and mails each person their results. pylendar only ever runs as you, on your own files, and never sends mail.

Installing

The fastest way to try it, without installing anything permanently, is with uv:

$ uvx pylendar

To keep it around as a tool on your PATH:

$ uv tool install pylendar

Or add it to a project:

$ uv add pylendar

Because it carries PEP 723 inline metadata, the single pylendar.py source file also runs as a stand-alone script with no installation at all: uv run --script path/to/pylendar.py. It also installs the traditional way with pip install pylendar.

Getting started

Create a starter calendar file with a few commented examples to copy from:

$ pylendar --init
pylendar: starter calendar written to ~/.calendar/calendar

Each line is a date, a single tab, and a description:

Jan 1	New Year's Day
Jul 4	US Independence Day [1776]
2028-07-14	Start of the LA Olympics
* 15	Mid-month reminder
May/MonSecond	2nd Monday in May
Easter	Easter Sunday
DecSolstice	Winter solstice

Add your own dates, then run it:

$ pylendar

By default pylendar shows today's events, plus the next three days when you run it on a Friday. A few options worth knowing:

• -A 30 looks 30 days ahead
• -w prints the weekday name in front of each event
• -t 2026-12-20 pretends it's a different day

Run pylendar --help for the full list, or man pylendar for the complete date-format reference.

Documentation

The manpage is the authoritative reference for every supported date format, command-line option, file-search path, and BSD compatibility note.

See also

• FreeBSD calendar(1) man page
• The Debian bsdmainutils package

License

BSD 3-Clause. See LICENSE.