ical

PyPI version CI Documentation

A modern Python RFC 5545 iCalendar library with built-in recurring event support — no companion libraries needed.

from ical.calendar_stream import IcsCalendarStream

cal = IcsCalendarStream.calendar_from_ics(ics_content)

# Recurring events are automatically expanded — just iterate
for event in cal.timeline:
    print(event.start, event.summary)

Why ical?

Most Python iCalendar libraries require two separate packages to handle recurring events:

# The typical ecosystem approach — two libraries, two APIs
import icalendar
import recurring_ical_events

cal = icalendar.Calendar.from_ical(ics_content)
events = recurring_ical_events.of(cal).between(start, end)

ical handles this natively with a single, unified Timeline interface, with a Pythonic API and validated inputs.

Feature ical icalendar ics.py
Built-in recurrence expansion ✅ ❌ needs recurring-ical-events ❌
Pythonic attribute access (event.start, event.summary) ✅ ❌ (event.get('DTSTART').dt) ✅
Input validation with clear error messages ✅ ❌ ❌
Full type annotations (py.typed) ✅ strict ty ✅ v7+ ❌
Application-level store API ✅ ❌ ❌
RFC 7986 / RFC 6868 / RFC 8536 ✅ partial ❌
Active maintenance ✅ ✅ ⚠️ stalled

Used By

Installation

uv add ical

Or with pip:

pip install ical

Requires Python 3.11+.

Quickstart

Reading an .ics file

Parse a calendar file and iterate over events in chronological order, with recurring events automatically expanded:

from pathlib import Path
from ical.calendar_stream import IcsCalendarStream
from ical.exceptions import CalendarParseError

filename = Path("calendar.ics")
with filename.open() as ics_file:
    try:
        cal = IcsCalendarStream.calendar_from_ics(ics_file.read())
    except CalendarParseError as err:
        print(f"Failed to parse '{filename}': {err}")
    else:
        for event in cal.timeline:
            print(event.start, event.summary)

Creating a calendar

from datetime import date
from ical.calendar import Calendar
from ical.event import Event

cal = Calendar()
cal.events.append(
    Event(summary="Team standup", start=date(2024, 1, 15), end=date(2024, 1, 16)),
)
for event in cal.timeline:
    print(event.summary)

Writing an .ics file

from pathlib import Path
from ical.calendar_stream import IcsCalendarStream

with Path("output.ics").open("w") as f:
    f.write(IcsCalendarStream.calendar_to_ics(cal))

Recurring events

Recurring events are stored once in the calendar but automatically expanded by the Timeline:

from datetime import date
from ical.calendar import Calendar
from ical.event import Event
from ical.types.recur import Recur

cal = Calendar()
cal.events.append(
    Event(
        summary="Weekly standup",
        start=date(2024, 1, 15),
        end=date(2024, 1, 16),
        rrule=Recur.from_rrule("FREQ=WEEKLY;COUNT=10"),
    )
)

# All 10 occurrences are expanded automatically
for event in cal.timeline:
    print(event.start, event.summary)

Application-level API

For managing calendar state in an application (ensuring timezones are set correctly, editing individual instances of recurring events, etc.), use ical.store:

from ical.store import EventStore
from ical.event import Event
from datetime import datetime, timezone

store = EventStore()
store.add(Event(summary="Meeting", start=datetime(2024, 1, 15, 9, tzinfo=timezone.utc)))

See the full documentation for the complete API reference.

Technical Guides

We publish detailed technical guides exploring the library's design:

Supported RFCs

  • RFC 5545 — Internet Calendaring and Scheduling Core Object Specification (iCalendar)
  • RFC 6868 — Parameter Value Encoding in iCalendar and vCard
  • RFC 7986 — New Properties for iCalendar
  • RFC 8536 — The Time Zone Information Format (TZif)

Comparison with other libraries

ical is designed for applications that need a complete, modern solution. You may prefer an alternative if:

  • icalendar — You need low-level control over raw iCalendar components, jCal (JSON) support, or maximum ecosystem compatibility. You prefer to expand recurring events manually and don't mind a second library (recurring-ical-events). You need to support legacy Python versions (3.8+) that ical does not target.
  • ics.py — You need a simple read-only script and do not require recurrence support. Note: no stable release since 0.7.2 (August 2021).

Contributing

See CONTRIBUTING.md for setup and development instructions.

Project links

Data verified by PyPI on
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for allen.porter from gravatar.com allen.porter

Credits

Author: Allen Porter

GitHub Statistics

Data verified by PyPI on 
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.11

Tags

icalendar ics calendar recurring rfc5545 vcalendar rrule vcard caldav

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ical-14.0.1.tar.gz (152.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ical-14.0.1-py3-none-any.whl (141.2 kB view details)

Uploaded Python 3

File details

Details for the file ical-14.0.1.tar.gz.

File metadata

  • Download URL: ical-14.0.1.tar.gz
  • Upload date:
  • Size: 152.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for ical-14.0.1.tar.gz
Algorithm Hash digest
SHA256 444df95a8eb710d87a196fd995b26f0ff7fcf8f779e9eeae898b4393a492be6d
MD5 4e16e079ce6d7f362c39fa0bdcd00965
BLAKE2b-256 050e8cdeb5e10f5ab7290d8affe256d1373635d33856b98a27688795d3b0f314

See more details on using hashes here.

Provenance

The following attestation bundles were made for ical-14.0.1.tar.gz:

Publisher: publish.yaml on allenporter/ical

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ical-14.0.1-py3-none-any.whl.

File metadata

  • Download URL: ical-14.0.1-py3-none-any.whl
  • Upload date:
  • Size: 141.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for ical-14.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 02ca21f76a7899dbc093b301d2fd2ce2a36c06a9a53e2cec442d80210724737f
MD5 2261f2257005d174a19b295189d26bb9
BLAKE2b-256 7fc63cc02d2bebf838126b4d3bed4800b108079a3e82cd39f2374bc6256733c6

See more details on using hashes here.

Provenance

The following attestation bundles were made for ical-14.0.1-py3-none-any.whl:

Publisher: publish.yaml on allenporter/ical

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

14.0.1

14.0.0

13.3.0

13.2.5

13.2.4

13.2.3

13.2.2

13.2.1

13.2.0

13.1.0

13.0.1

12.1.3

12.1.2

12.1.1

12.1.0

12.0.0

11.1.0

11.0.0

10.0.4

10.0.3

10.0.2

10.0.1

10.0.0

9.2.5

9.2.4

9.2.3

9.2.2

9.2.1

9.2.0

9.1.0

9.0.3

9.0.2

9.0.1

8.3.1

8.3.0

8.2.0

8.1.1

8.1.0

8.0.2

8.0.1

8.0.0

7.0.3

7.0.2

7.0.1

7.0.0

6.1.1

6.1.0

6.0.0

5.1.1

5.1.0

5.0.1

5.0.0

4.5.4

4.5.2

4.5.1

4.5.0

4.4.0

4.3.0

4.2.9

4.2.8

4.2.7

4.2.6

4.2.5

4.2.4

4.2.3

4.2.2

4.2.1

4.2.0

4.1.2

4.1.1

4.1.0

4.0.1

4.0.0

3.0.1

3.0.0

2.1.0

2.0.0

1.2.0

1.1.0

1.0.0

0.2.0

0.1.0

0.0.4

0.0.3

0.0.1

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page