Install & Compatibility
Where this runs
tested against v0.3.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.526s · 30.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 0.483s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
events
✓ from icalevents.icalevents import events
The primary class for synchronous event fetching.
events_async
✓ from icalevents.icalevents import events_async, latest_events, all_done
For asynchronous event fetching, typically used with `all_done` and `latest_events`.
This quickstart demonstrates how to fetch and display iCalendar events from a given URL within a specific date range. It includes a placeholder for an iCal URL, emphasizing the need for a valid source. The `fix_apple=True` parameter is included as a common best practice when dealing with Apple iCal sources.
import os
from datetime import datetime, timedelta
from icalevents.icalevents import events
# Replace with your actual iCal URL, e.g., from Google Calendar or iCloud
ICAL_URL = os.environ.get('ICAL_SOURCE_URL', 'https://example.com/path/to/your/calendar.ics')
if not ICAL_URL or ICAL_URL == 'https://example.com/path/to/your/calendar.ics':
print("Please set the ICAL_SOURCE_URL environment variable or replace the placeholder in the code.")
else:
# Define a time range for events (e.g., next 7 days)
start_date = datetime.now()
end_date = start_date + timedelta(days=7)
# Fetch events
try:
calendar_events = events(ICAL_URL, start=start_date, end=end_date, fix_apple=True)
if calendar_events:
print(f"Found {len(calendar_events)} events between {start_date.date()} and {end_date.date()}:")
for event in calendar_events:
print(f"- {event.summary} (Start: {event.start}, End: {event.end})")
else:
print("No events found in the specified range.")
except Exception as e:
print(f"Error fetching events: {e}")
print("Ensure the ICAL_SOURCE_URL is correct and accessible.")
Debug
Known issues
gotchaWhen fetching events from Apple iCal sources, issues with timezone data are common. Always consider using the `fix_apple=True` parameter in the `events()` function to mitigate these known inconsistencies.fixPass `fix_apple=True` to the `events()` or `events_async()` calls.
affects: All versions
breakingiCalEvents relies on the `icalendar` library. `icalendar` version 7.x, released in February 2026, dropped support for Python 3.8 and 3.9. While `icalevents` 0.3.1 requires Python >=3.9, users with older `icalevents` versions or specific dependency setups might encounter `icalendar` compatibility issues if they upgrade `icalendar` to 7.x on Python 3.8/3.9.fixEnsure your Python environment is 3.10 or newer if using `icalendar` 7.x, or pin `icalendar` to a compatible older version (e.g., `<7.0.0`) if strictly needing Python 3.9 or older.
affects: icalendar 7.x and above (indirectly affecting icalevents on Python <3.10)
gotchaAsynchronous event fetching with `events_async` requires a specific pattern: initiate with `events_async`, then repeatedly check `all_done(key)` until the request finishes, and finally retrieve results with `latest_events(key)`. Failing to follow this sequence can lead to incomplete data or blocking.fixImplement the full async pattern: `key = events_async(...)`, then `while not all_done(key): time.sleep(polling_interval)`, and finally `result = latest_events(key)`.
affects: All versions with asynchronous features
gotchaExternal iCal calendar services (e.g., Google Calendar, iCloud) may have their own caching or synchronization delays. Changes made in the source calendar might not be immediately reflected when `icalevents` fetches the data, leading to stale information. This is an external service limitation, not a library bug.fixAccount for potential delays by adjusting refresh intervals or informing users that real-time updates may not be guaranteed by the external service. Consider implementing mechanisms to force a refresh on the source calendar if available.
affects: All versions (due to external service behavior)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'icalendar.windows_to_olson'
This error typically occurs when the `icalevents` library, or a dependency like `recurring-ical-events`, is used with an incompatible version of the `icalendar` library. The `windows_to_olson` module was removed or moved in newer versions of `icalendar`.
fixUpgrade the `icalendar` package to a compatible version or downgrade `icalevents` and its related dependencies. A common fix is to ensure `icalendar` is at version 6.x or newer, and `icalevents` is also up-to-date. If using Home Assistant, this might involve ensuring the Home Assistant Core is updated, as it manages these dependencies.
AttributeError: module 'icalendar' has no attribute 'InvalidCalendar'
This error arises from a version conflict between `icalendar` and `recurring_ical_events`, a dependency that `icalevents` might rely on (especially in contexts like Home Assistant). The `InvalidCalendar` attribute was likely removed or renamed in a newer `icalendar` version, which an older `recurring_ical_events` or `icalevents` is still trying to access.
fixEnsure that `icalendar` and `recurring_ical_events` (if directly used or as a dependency) are at compatible versions. Often, updating all related packages, including `icalevents` and `icalendar`, to their latest stable releases resolves the conflict. In some specific integration contexts, like Home Assistant, manually adjusting dependency versions in configuration might be necessary if automatic updates don't fix it.
Platform error: sensor - Requirements for waste_collection_schedule not found: ['icalevents']
This specific error is encountered in Home Assistant when the `icalevents` Python package, a dependency for integrations like `waste_collection_schedule`, is not installed or cannot be properly installed within the Home Assistant operating system environment.
fixAttempt to manually install `icalevents` using pip within the Home Assistant environment if possible, or ensure the Home Assistant Core is fully updated, as it usually manages the dependencies. If the issue persists, it might indicate a broader problem with Python package installation within that particular Home Assistant OS version.
from icalevents import events
This is a common incorrect import pattern. The `events` class is not directly available under the top-level `icalevents` package. It resides within the `icalevents.icalevents` submodule.
fixThe correct way to import the `events` class is `from icalevents.icalevents import events`.
Upgrade
Version history
0.3.1latest on PyPI · released Sep 26, 2025
Audit
Dependencies
icalendarrequiredicalevents is built on top of the icalendar library for iCal parsing.