ics

library0.7.3pypypi✓ verified 84d ago

ics is a Python library for parsing, creating, and manipulating iCalendar files (RFC 5545). It provides an object-oriented API to work with Calendars, Events, Todos, Alarms, and other iCalendar components. The current version is 0.7.2, and releases occur periodically for bug fixes, minor enhancements, and major version upgrades that introduce breaking changes.

serialization

pip install ics

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ICS

ics

serializationpythonv0.7.3

Install

2.1s avg

Import

295ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.7.3 · 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.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.308s · 23.9MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.1s · import 0.282s · 24MB

22MB installed

● package 22MB

Code

Verified usage

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

Calendar

✓ from ics import Calendar

Event

✓ from ics import Event

Alarm

✓ from ics import Alarm

Attendee

✓ from ics import Attendee

Organizer

✓ from ics import Organizer

This quickstart demonstrates how to create a new iCalendar object, add events with basic properties like name, start time, and duration, and then output the calendar as an iCalendar string. You can also save it to a .ics file.

from ics import Calendar, Event from datetime import datetime # Create a new Calendar c = Calendar() # Create a new Event e = Event() e.name = "My cool event" e.begin = datetime(2024, 1, 1, 10, 0, 0) e.duration = {'hours': 1} e.description = "This is a description for my event." # Add the event to the calendar c.events.add(e) # Add another event e2 = Event(name="Another event", begin='2024-01-02 14:30:00') c.events.add(e2) # Print the iCalendar string print(str(c)) # To save to a file (example): # with open('my_calendar.ics', 'w') as f: # f.writelines(c)

Debug

Known issues

breakingPython 2 support was completely dropped in version 0.5. The library now only supports Python 3.5 and above.

fix

Upgrade to Python 3.5+ if you are on an older Python 2.x environment.

affects: <0.5

breakingVersion 0.6 dropped support for Python 3.5 and introduced `TatSu` as a new dependency for parsing. Additionally, the previously private `._unused` attribute was renamed to the public `.extra`.

fix

Ensure your environment is Python 3.6+ and install `ics` which will pull `TatSu`. Update code from `._unused` to `.extra`.

affects: <0.6

breakingIn version 0.7, `Attendee` and `Organizer` attributes can no longer be set directly to a string. They must be instances of their respective classes.

fix

Instead of `e.organizer = 'mailto:test@example.com'`, use `from ics import Organizer; e.organizer = Organizer(email='test@example.com')`.

affects: <0.7

deprecatedThe `Calendar.str()` method and `Calendar.iter()` will undergo breaking changes in version 0.8. Warnings are emitted in 0.7.1 and later.

fix

Review the upcoming 0.8 release notes for changes to these methods. Consider preparing for potential adaptation of how calendars are serialized or iterated.

affects: >=0.7.1

gotchaVersion 0.7.1 introduced a dependency on `attrs`. Version 0.7.2 further specified a lower bound of `attrs>=19.1.0`. Users upgrading from older `ics` versions might encounter issues if their `attrs` dependency is too old.

fix

Ensure `attrs` is up-to-date in your environment, ideally `pip install 'attrs>=19.1.0'` before installing `ics` or allow `pip install ics` to handle the dependency update.

affects: >=0.7.1

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ics'

This error occurs when the 'ics' library is not installed in the Python environment or the Python interpreter cannot find it.

fix

Ensure the library is installed using pip: `pip install ics`

TypeError: can't compare offset-naive and offset-aware datetimes

This typically arises when attempting to compare or operate on `datetime` objects, where some have timezone information (offset-aware) and others do not (offset-naive), which `ics.py` handles specifically by converting datetimes to UTC at parsing time or expecting aware datetimes for consistent behavior.

fix

Ensure all `datetime` objects used with `ics` are timezone-aware and, ideally, in UTC. Use libraries like `pytz` or `dateutil` to create or convert `datetime` objects to be timezone-aware. Example: `from datetime import datetime, timezone; event.begin = datetime(2023, 1, 1, 10, 0, 0, tzinfo=timezone.utc)`

AttributeError: 'int' object has no attribute 'replace'

This error happens when an `ics` event property, such as `event.name`, is assigned a non-string value (like an integer), and the library internally attempts to perform string operations (e.g., `replace`) on it.

fix

Ensure that properties like `event.name`, `event.description`, etc., are assigned string values. Convert non-string data to strings explicitly before assignment. Example: `e.name = str(i)` instead of `e.name = i`

ImportError: cannot import name 'Calendar' from 'icalendar'

This error indicates a confusion between the `ics` library and the `icalendar` library. You are likely trying to import `Calendar` from the `icalendar` package when intending to use the `ics.py` library's `Calendar` class.

fix

If you intend to use the `ics` library, import `Calendar` from it directly: `from ics import Calendar`. If you truly mean to use the `icalendar` library, ensure it is installed (`pip install icalendar`) and that your code correctly uses its API.

Upgrade

Version history

0.7.3latest on PyPI · released Apr 15, 2026

Audit

Dependencies

attrsrequiredUsed for attribute handling in components. Required >=19.1.0 since v0.7.2.

TatSurequiredProvides the PEG parser for iCalendar files. Required since v0.6.

arrowrequiredUsed for date and time handling. Heavily integrated but no strict upper bound since v0.7.1.

Agent activity

10 hits · last 30 days

node

Resources

githubhttp://github.com/C4ptainCrunch/ics.py ↗

packagehttps://pypi.org/project/ics/ ↗

homepagehttps://icspy.readthedocs.io ↗