Skip to main content
`Ctrl`+`K`

# Internet Calendaring and Scheduling (iCalendar) for Python

The icalendar package is a RFC 5545 compatible parser/generator for iCalendar files.

Homepage:

  https://icalendar.readthedocs.io

Community Discussions:

  collective/icalendar#discussions

Issue Tracker:

  collective/icalendar#issues

Code:

  collective/icalendar

Dependencies:

  python-dateutil and tzdata.

License:

  BSD

## Quick start guide

`icalendar` enables you to create, inspect and modify calendaring information with Python.

To install the package, run:

    pip install icalendar

### Inspect Files

You can open an `.ics` file and see all the events:

    >>> import icalendar
    >>> from pathlib import Path
    >>> ics_path = Path("src/icalendar/tests/calendars/example.ics")
    >>> calendar = icalendar.Calendar.from_ical(ics_path.read_bytes())
    >>> for event in calendar.events:
    ...     print(event.get("SUMMARY"))
    New Year's Day
    Orthodox Christmas
    International Women's Day

### Modify Content

Such a calendar can then be edited and saved again.

    >>> calendar.calendar_name = "My Modified Calendar"  # modify
    >>> print(calendar.to_ical()[:121])  # save modification
    BEGIN:VCALENDAR
    VERSION:2.0
    PRODID:collective/icalendar
    CALSCALE:GREGORIAN
    METHOD:PUBLISH
    NAME:My Modified Calendar

### Create Events, TODOs, Journals, Alarms, …

`icalendar` supports the creation and parsing of all kinds of objects in the iCalendar (RFC 5545) standard.

    >>> icalendar.Event()  # events
    VEVENT({})
    >>> icalendar.FreeBusy()  # free/busy times
    VFREEBUSY({})
    >>> icalendar.Todo()  # Todo list entries
    VTODO({})
    >>> icalendar.Alarm()  # Alarms e.g. for events
    VALARM({})
    >>> icalendar.Journal()   # Journal entries
    VJOURNAL({})

Have a look at more examples.

### Use timezones of your choice

With `icalendar`, you can localize your events to take place in different timezones. `zoneinfo`, `dateutil.tz` and `pytz` are compatible with `icalendar`. This example creates an event that uses all of the timezone implementations with the same result:

    >>> import pytz, zoneinfo, dateutil.tz  # timezone libraries
    >>> import datetime, icalendar
    >>> e = icalendar.Event()
    >>> tz = dateutil.tz.tzstr("Europe/London")
    >>> e["X-DT-DATEUTIL"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
    >>> tz = pytz.timezone("Europe/London")
    >>> e["X-DT-USE-PYTZ"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
    >>> tz = zoneinfo.ZoneInfo("Europe/London")
    >>> e["X-DT-ZONEINFO"] = icalendar.vDatetime(datetime.datetime(2024, 6, 19, 10, 1, tzinfo=tz))
    >>> print(e.to_ical())  # the libraries yield the same result
    BEGIN:VEVENT
    X-DT-DATEUTIL;TZID=Europe/London:20240619T100100
    X-DT-USE-PYTZ;TZID=Europe/London:20240619T100100
    X-DT-ZONEINFO;TZID=Europe/London:20240619T100100
    END:VEVENT

### Version 6 with zoneinfo

Version 6 of `icalendar` switches the timezone implementation to `zoneinfo`. This only affects you if you parse `icalendar` objects with `from_ical()`. The functionality is extended and is tested since 6.0.0 with both timezone implementations `pytz` and `zoneinfo`.

By default and since 6.0.0, `zoneinfo` timezones are created.

    >>> dt = icalendar.Calendar.example("timezoned").events[0].start
    >>> dt.tzinfo
    ZoneInfo(key='Europe/Vienna')

If you would like to continue to receive `pytz` timezones in parse results, you can receive all the latest updates, and switch back to earlier behavior:

    >>> icalendar.use_pytz()
    >>> dt = icalendar.Calendar.example("timezoned").events[0].start
    >>> dt.tzinfo
    <DstTzInfo 'Europe/Vienna' CET+1:00:00 STD>

Version 6 is on branch main. It is compatible with Python versions 3.8 - 3.13, and PyPy3. We expect the `main` branch with versions `6+` to receive the latest updates and features.

## Related projects

- icalevents. It is built on top of icalendar and allows you to query iCal files and get the events happening on specific dates. It manages recurrent events as well.

- recurring-ical-events. Library to query an `icalendar.Calendar` object for events and other components happening at a certain date or within a certain time.

- x-wr-timezone. Library and command line tool to make `icalendar.Calendar` objects and files from Google Calendar (using the non-standard `X-WR-TIMEZONE` property) compliant with the standard (RFC 5545).

- ics-query. Command line tool to query iCalendar files for occurrences of events and other components.

- icalendar-compatibility - access to event data compatible with RFC5545 and different implementations

## Further Reading

You can find out more about this project:

- Contributing

- Changelog

- License

## Contents

- About
- Installing iCalendar
  - Python Package with `pip`
  - Debian or Ubuntu
  - Development Setup
  - Installing Python
  - Install Tox
  - Running Tests
  - Code Style
  - Accessing a `tox` environment
  - Install `icalendar` Manually
  - Build the documentation
- iCalendar package
  - Compatibility
  - iCalendar file structure
  - Components
  - Subcomponents
  - Value types
  - Property parameters
  - Example
- More documentation
- API Reference
  - icalendar.attr
  - icalendar.alarms
  - icalendar.cal
  - icalendar.caselessdict
  - icalendar.cli
  - icalendar.enums
  - icalendar.error
  - icalendar.param
  - icalendar.parser
  - icalendar.parser_tools
  - icalendar.prop
  - icalendar.tools
  - icalendar.timezone
  - icalendar.version
- iCalendar utility
  - view
- icalendar contributors
- Maintenance
  - Maintainers
  - Collaborators
  - New Releases
  - Links
  - Updating Python Versions
- License
- Changelog
  - 6.3.1 (2025-05-20)
  - 6.3.0 (2025-05-15)
  - 6.2.0 (2025-05-07)
  - 6.1.3 (2025-03-19)
  - 6.1.2 (2025-03-19)
  - 6.1.1 (2025-01-18)
  - 6.1.0 (2024-11-22)
  - 6.0.1 (2024-10-13)
  - 6.0.0 (2024-09-28)
  - 6.0.0a0 (2024-07-03)
  - 5.0.13 (2024-06-20)
  - 5.0.12 (2024-03-19)
  - 5.0.11 (2023-11-03)
  - 5.0.10 (2023-09-26)
  - 5.0.9 (2023-09-24)
  - 5.0.8 (2023-09-18)
  - 5.0.7 (2023-05-29)
  - 5.0.6 (2023-05-26)
  - 5.0.5 (2023-04-13)
  - 5.0.4 (2022-12-29)
  - 5.0.3 (2022-11-23)
  - 5.0.2 (2022-11-03)
  - 5.0.1 (2022-10-22)
  - 5.0.0 (2022-10-17)
  - 5.0.0a1 (2022-07-11)
  - 4.1.0 (2022-07-11)
  - 4.0.9 (2021-10-16)
  - 4.0.8 (2021-10-07)
  - 4.0.7 (2020-09-07)
  - 4.0.6 (2020-05-06)
  - 4.0.5 (2020-03-21)
  - 4.0.4 (2019-11-25)
  - 4.0.3 (2018-10-10)
  - 4.0.2 (2018-06-20)
  - 4.0.1 (2018-02-11)
  - 4.0.0 (2017-11-08)
  - 3.12 (2017-11-07)
  - 3.11.7 (2017-08-27)
  - 3.11.6 (2017-08-04)
  - 3.11.5 (2017-07-03)
  - 3.11.4 (2017-05-10)
  - 3.11.3 (2017-02-15)
  - 3.11.2 (2017-01-12)
  - 3.11.1 (2016-12-19)
  - 3.11 (2016-11-18)
  - 3.10 (2016-05-26)
  - 3.9.2 (2016-02-05)
  - 3.9.1 (2015-09-08)
  - 3.9.0 (2015-03-24)
  - 3.8.4 (2014-11-01)
  - 3.8.3 (2014-08-26)
  - 3.8.2 (2014-07-22)
  - 3.8.1 (2014-07-17)
  - 3.8 (2014-07-17)
  - 3.7 (2014-06-02)
  - 3.6.2 (2014-04-05)
  - 3.6.1 (2014-01-13)
  - 3.6 (2014-01-06)
  - 3.5 (2013-07-03)
  - 3.4 (2013-04-24)
  - 3.3 (2013-02-08)
  - 3.2 (2012-11-27)
  - 3.1 (2012-09-05)
  - 3.0.1b2 (2012-03-01)
  - 3.0.1b1 (2012-02-24)
  - 3.0
  - 2.2 (2011-08-24)
  - 2.1 (2009-12-14)
  - 2.0.1 (2008-07-11)
  - 2.0 (2008-07-11)
  - 1.2 (2006-11-25)
  - 1.1 (2006-11-23)
  - 1.0 (2006-08-03)
  - 0.11 (2005-11-08)
  - 0.10 (2005-04-28)

- Contributing
- Security Policy