Registry / serialization / icalendar

icalendar

JSON →
library7.3.0pypypi✓ verified 24d ago

icalendar is an RFC 5545 compatible parser and generator of iCalendar files. It facilitates the creation, modification, and parsing of calendar data (events, todos, journals) in Python. The library is actively maintained with frequent patch releases within major versions, and new major versions are released occasionally to introduce breaking changes and new features.

pip install icalendar
INSTALL
IMPORT
SIG · ICALENDAR
I
icalendar
serializationpythonv7.3.0
Install
2.1s avg
Import
340ms
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v7.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.358s · 26.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.1s · import 0.322s · 27MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Calendar
from icalendar import Calendar
Event
from icalendar import Event
vRecur
from icalendar import vRecur
Used for defining recurrence rules for events.
vDDDTypes
from icalendar import vDDDTypes
A class for handling iCalendar datetime/date/duration types, especially for advanced parsing/serialization.

This quickstart demonstrates how to create an iCalendar object with an event and a recurrence rule, serialize it to an iCalendar string, and then parse that string back into a Python object to extract event details.

import datetime from icalendar import Calendar, Event, vRecur # --- Create an iCalendar --- cal = Calendar() cal.add('prodid', '-//My Organisation//Example Calendar App//EN') cal.add('version', '2.0') event = Event() event.add('summary', 'Team Standup') # Always use timezone-aware datetimes for iCalendar event.add('dtstart', datetime.datetime(2024, 7, 10, 9, 0, 0, tzinfo=datetime.timezone.utc)) event.add('dtend', datetime.datetime(2024, 7, 10, 9, 15, 0, tzinfo=datetime.timezone.utc)) event.add('dtstamp', datetime.datetime.now(datetime.timezone.utc)) event['uid'] = 'event_20240710_standup@example.com' event.add('location', 'Online Meeting Room') # Add a recurrence rule (e.g., daily for 5 occurrences) rrule = vRecur({'freq': ['DAILY'], 'count': [5]}) event.add('rrule', rrule) cal.add_component(event) # Serialize to iCalendar format ical_string = cal.to_ical().decode('utf-8') print("--- Generated iCalendar ---") print(ical_string) # --- Parse an iCalendar --- print("\n--- Parsed iCalendar ---") parsed_cal = Calendar.from_ical(ical_string) for component in parsed_cal.walk(): if component.name == 'VEVENT': print(f"Summary: {component.get('summary')}") print(f"Start: {component.get('dtstart').dt}") print(f"End: {component.get('dtend').dt}") if 'rrule' in component: print(f"Recurrence Rule: {component.get('rrule')}")
Debug
Known issues
breakingIn v7.0.0, the `from_ical` method on `Calendar`, `Event`, and other components now expects a string (`str`) or bytes (`bytes`) object directly, instead of a file-like object.
fix
If you were reading from a file, explicitly read the content into a string or bytes first: `ical_data = file.read(); cal = Calendar.from_ical(ical_data)`.
affects: >=7.0.0
breakingVersion 7.0.0 introduced significant changes to how datetime objects are handled, aligning more strictly with Python's standard `datetime` module. Floating datetimes (without `tzinfo`) are now treated as UTC by default if no `TZID` is specified.
fix
Always use timezone-aware `datetime` objects, preferably `datetime.timezone.utc`, when adding event times to avoid ambiguity and ensure correct RFC 5545 compliance.
affects: >=7.0.0
gotchaIncorrect timezone handling is a common source of errors. If datetimes are not timezone-aware, `icalendar` might make assumptions (e.g., UTC) that don't match your intended local time.
fix
Explicitly provide `tzinfo` for all `datetime` objects, e.g., using `datetime.datetime.now(datetime.timezone.utc)` or `datetime.datetime(..., tzinfo=zoneinfo.ZoneInfo('America/New_York'))` (Python >=3.9). For older Python, `pytz` is commonly used.
affects: all
breakingIn v5.0.0, `vDDDTypes` (used for date/datetime/duration properties) is no longer directly callable. Instead, you must use its static methods `vDDDTypes.from_str()` for parsing and `vDDDTypes.to_ical()` for serialization.
fix
Update calls from `vDDDTypes(value)` to `vDDDTypes.from_str(value)` or directly use `component.add('property', value)` for common cases where `icalendar` handles the type conversion automatically.
affects: >=5.0.0
Errors
Common errors & fixes
ValueError: You must use datetime, date, timedelta or time
This error occurs when attempting to assign a value to a datetime-related property (like DTSTART or DTEND) using an unsupported data type, such as a string, instead of a Python `datetime`, `date`, `timedelta`, or `time` object.
fix
Ensure that datetime properties are assigned with a proper Python datetime object. If you have a string, parse it into a datetime object first, or use `icalendar.vDatetime` if you need specific iCalendar value handling.
ValueError: Content line could not be parsed into parts
This error typically indicates that the iCalendar data being parsed is malformed or contains syntax errors, preventing `icalendar` from correctly interpreting a line according to the RFC 5545 specification.
fix
Validate the input iCalendar data for correctness (e.g., using an online validator like icalendar.org/validator). Common issues include incorrect line endings, missing required components (BEGIN/END:VCALENDAR, VEVENT), or improperly formatted properties/parameters.
ValueError: A VCALENDAR must have at most one METHOD
The iCalendar specification states that a VCALENDAR component should contain at most one 'METHOD' property. This error arises when you try to add multiple 'METHOD' properties to a single `icalendar.Calendar` object.
fix
Review your code to ensure that you are adding only one 'METHOD' property (e.g., 'METHOD:PUBLISH') to your `icalendar.Calendar` instance. If different methods are needed, they should be in separate VCALENDAR components.
Upgrade
Version history
7.3.0latest on PyPI · released Aug 19, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
8
Resources
icalendar — pip install icalendar · libregistry