RRULE iCal Generator (RFC 5545)

RRULE: the calendar-aware recurrence grammar of iCalendar

RRULE stands for Recurrence Rule and is the property in the iCalendar format (RFC 5545, Section 3.8.5.3) that describes how a VEVENT, VTODO or VJOURNAL repeats. Instead of materialising every occurrence on disk, the rule is stored once and clients expand it on the fly — that is why a "weekly meeting forever" event takes a few dozen bytes instead of thousands of rows. Unlike a cron expression, RRULE is calendar-aware: it understands months of varying length, weekdays, leap years, ordinal positions ("last Friday") and the difference between local time and UTC.

The minimum rule is RRULE:FREQ=DAILY;COUNT=10. The FREQ token accepts SECONDLY, MINUTELY, HOURLY, DAILY, WEEKLY, MONTHLY and YEARLY. Modifiers refine the cadence: INTERVAL (every N units — INTERVAL=2 on a weekly rule means every two weeks), COUNT (exactly N occurrences), UNTIL (terminate at a specific UTC instant), BYDAY (a comma list of MO,TU,WE,TH,FR,SA,SU), BYMONTHDAY (1,15 for the 1st and 15th), BYMONTH, BYSETPOS (pick the Nth occurrence within a set) and WKST (which day starts the week — defaults to Monday).

Worked examples

# Daily for ten days
RRULE:FREQ=DAILY;COUNT=10

# Every Friday, forever
RRULE:FREQ=WEEKLY;BYDAY=FR

# Last Friday of the month
RRULE:FREQ=MONTHLY;BYDAY=-1FR

# Birthday on May 15th every year
RRULE:FREQ=YEARLY;BYMONTH=5;BYMONTHDAY=15

# 1st and 15th of every month
RRULE:FREQ=MONTHLY;BYMONTHDAY=1,15

# Mon/Wed/Fri for 12 weeks
RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=12

EXDATE, RDATE and complex patterns

Real schedules are messy. To skip an occurrence (a one-off holiday cancellation, say), add an EXDATE line with the exact start time of the skipped instance. To inject an extra occurrence not covered by the rule, use RDATE. Combined with BYSETPOS ("the second Tuesday of each month" → FREQ=MONTHLY;BYDAY=TU;BYSETPOS=2), the four-property combo covers almost every business rule a calendar app will ever need without falling back to materialising rows.

Compatibility, libraries and DST

RRULE is supported by every major calendar client: Google Calendar, Microsoft Outlook, Apple Calendar, Fantastical, Notion Calendar, Thunderbird Lightning and any CalDAV server (Nextcloud, Radicale, Baikal, Apple iCloud). On the code side, mature libraries handle expansion: rrule.js (Jakub Roztocil, the de-facto JS implementation — also drives this generator), python-dateutil's rrule module, iCal4j (Java) and recurring_events_for (Ruby). Edge cases to test: daylight saving transitions (an event at 02:30 local during a spring-forward simply does not exist that day), leap years (Feb 29 events), and end-of-month variations (the 31st in February — most clients silently drop it, but check).

Frequently asked questions

Why not just use cron? Cron is minute-level and system-level — it does not understand calendars, weekdays, ordinals like "last Friday" or holidays. RRULE is calendar-aware and lives inside an .ics event so it travels with the meeting invite itself.

Is the support really universal? Yes — Google, Apple, Microsoft and every CalDAV client read and write RRULE because it is the only recurrence grammar in the iCalendar standard.

Can I combine COUNT and UNTIL? No — RFC 5545 forbids it. Use one or the other; UNTIL takes precedence in clients that violate the spec.

What does WKST change? It only matters with BYWEEKNO or weekly rules that span week boundaries. In Brazil weeks are commonly considered to start on Sunday (WKST=SU); in ISO 8601 (and the RRULE default) they start on Monday (WKST=MO).