Install & Compatibility
Where this runs
tested against v6.3.2.20260712 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 72.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 1.8s · import 0.000s · 19MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Calendar
✓ from icalendar_stubs import Calendar
✗ from icalendar-stubs import Calendar
This quickstart demonstrates how to create a basic iCalendar file with an event using the `icalendar` library, for which `types-icalendar` provides type hints. It covers initializing a calendar, adding essential properties, creating and populating an event, and then serializing the calendar to a string. Note the use of `zoneinfo` for timezone-aware datetimes, which is crucial for iCalendar compatibility.
from icalendar import Calendar, Event, vText
from datetime import datetime
import zoneinfo
# Create a new Calendar object
cal = Calendar()
cal.add('prodid', '-//My Company//My Calendar App//EN')
cal.add('version', '2.0')
cal.add('summary', 'My Awesome Calendar')
# Create an Event
event = Event()
event.add('summary', 'Meeting with Client X')
event.add('dtstart', datetime(2026, 4, 15, 10, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))
event.add('dtend', datetime(2026, 4, 15, 11, 0, 0, tzinfo=zoneinfo.ZoneInfo('America/New_York')))
event.add('description', 'Discuss Q2 strategy and project roadmap.')
event.add('location', vText('Conference Room A'))
event['uid'] = '20260415T100000-abcd-1234@example.com'
# Add the event to the calendar
cal.add_component(event)
# Serialize the calendar to iCalendar format
ical_string = cal.to_ical().decode('utf-8')
print(ical_string)
# Example of parsing an iCalendar string
# parsed_cal = Calendar.from_ical(ical_string)
# for component in parsed_cal.walk():
# if component.name == 'VEVENT':
# print(component.get('summary'))
Debug
Known issues
breakingIf using `icalendar` version 7.0.0 or newer, `types-icalendar` should be uninstalled. `icalendar` now includes its own type annotations, which can cause conflicts or redundancy with `types-icalendar`.fixUninstall `types-icalendar`: `pip uninstall types-icalendar`. Ensure `icalendar` is up to date: `pip install --upgrade icalendar`.
affects: icalendar >= 7.0.0
breakingThe `icalendar` runtime library, for which `types-icalendar` provides stubs, dropped support for Python 3.8 and 3.9 in `icalendar` version 7.0.3. The `types-icalendar` package itself requires Python >=3.10, aligning with the current `icalendar` branch it supports (e.g., `icalendar==6.3.2`).fixUpgrade to Python 3.10 or newer. Ensure your `icalendar` version matches the `types-icalendar` target (e.g., `icalendar==6.3.2` for `types-icalendar==6.3.2.20260408`).
affects: icalendar < 7.0.3 and Python < 3.10
gotchaIn `icalendar` versions prior to 7.0.3, the `Component.decoded()` method for text properties returned bytes. From version 7.0.3 onwards, it returns a string. Code relying on the byte return type will break if `icalendar` is updated.fixUpdate code to expect a string return type from `Component.decoded()` for text properties. If supporting both old and new `icalendar` versions, check `isinstance()` for compatibility.
affects: icalendar < 7.0.3
gotchaAccording to RFC 5545, `Calendar` objects in `icalendar` require `PRODID` and `VERSION` properties. Forgetting to add these can lead to invalid iCalendar files, even if the code type-checks. Newer `icalendar` versions (e.g., 7.0.0+) may provide enhanced methods for automatic `PRODID` generation.fixAlways add `cal.add('prodid', '...')` and `cal.add('version', '2.0')` when creating a new `Calendar` object. affects: All versions of icalendar
gotchaIncorrect handling of timezones with `datetime` objects can lead to silently corrupted or invalid iCalendar data. `icalendar` supports multiple timezone implementations (e.g., `zoneinfo`, `dateutil.tz`, `pytz`). Using naive `datetime` objects for `dtstart` or `dtend` without proper timezone information is a common mistake.fixAlways use timezone-aware `datetime` objects (e.g., `datetime(..., tzinfo=zoneinfo.ZoneInfo('Europe/Berlin'))`) for event start/end times to ensure correct iCalendar output and parsing. affects: All versions of icalendar
Upgrade
Version history
6.3.2.20260712latest on PyPI · released Jul 12, 2026
Audit
Dependencies
icalendarrequiredThis package provides type stubs for the `icalendar` library, which is required at runtime.
python-dateutilrequiredTransitive dependency of `icalendar` for date/time parsing and manipulation.
tzdatarequiredTransitive dependency of `icalendar` for timezone information, especially when using Python's `zoneinfo` module.