Create event with attendees

In this tutorial, you'll create an iCalendar file with events and attendees.

Creating a calendar

First, you create a Calendar, the highest component type which can contain one or more subcomponents. The Calendar component itself contains its own properties. When you create one using the new() method, it automatically sets the minimal required properties.

>>> from icalendar import Calendar
>>> calendar = Calendar.new()

After creating a new calendar, you can view its properties by using to_ical(), which generates a bytes object of the component, and decode(), which converts the output to Unicode, making it easier to read.

>>> print(calendar.to_ical().decode())
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//collective//icalendar//7.0.0//EN
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VCALENDAR

Notice that by default a calendar contains the version, product identifier (PRODID), and a unique identifier (UID). All these properties are required for a calendar. You can also set and change these properties.

>>> calendar.prodid = "-//icalendar//example.com//EN"

Here you change the product identifier and print the revised component. The output confirms the change:

>>> print(calendar.to_ical().decode())
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//icalendar//example.com//EN
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VCALENDAR

Adding an event

Now that you have a base calendar, you can add an event to it. You can similarly create an Event subcomponent using the new() method, which includes appropriate defaults. You can also set these properties on creation.

>>> from icalendar import Event
>>> import datetime as dt
>>> import zoneinfo
>>>
>>> event = Event.new(
...     start=dt.datetime(2026, 3, 21, 6, 30, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
...     end=dt.datetime(2026, 3, 21, 7, 30, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
... )

This creates an event with a start and end date and time defined using datetime with a timezone. The output shows your new event:

>>> print(event.to_ical().decode())
BEGIN:VEVENT
DTSTART:20260321T063000Z
DTEND:20260321T073000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT

Notice that the event component includes the start and end dates with their times (DTSTART and DTEND) along with a unique identifier (UID), and its creation timestamp (DTSTAMP).

Similar to the calendar event, you can edit these properties or add new ones.

>>> event.summary = "Pick up bicycle from the workshop."

Using the add() method on a component, you can add new properties with their name and value. The summary property represents the title of an event.

To use an event, you must add it to the calendar.

>>> calendar.add_component(event)

You can add the newly created event to the previously created calendar using add_component(). Now print the calendar to verify everything that it contains:

>>> print(calendar.to_ical().decode())
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//icalendar//example.com//EN
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
BEGIN:VEVENT
SUMMARY:Pick up bicycle from the workshop.
DTSTART:20260321T063000Z
DTEND:20260321T073000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT
END:VCALENDAR

You can now see your calendar with the event nested inside.

Creating events with attendees

Next, create a second event in your calendar that includes attendees.

>>> from icalendar import vCalAddress
>>> ride_event = Event.new(
...     start=dt.datetime(2026, 3, 28, 7, 00, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
...     end=dt.datetime(2026, 3, 28, 13, 30, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
...     summary="Morning ride with the team.",
...     attendees=[
...         vCalAddress("mailto:me@example.com"),
...         vCalAddress("mailto:another_friend@example.com"),
...     ]
... )

You've now created an event with a set start and end date and time, including a timezone, the event has a title, and lists two attendees by their email address. The output confirms your additions:

>>> print(ride_event.to_ical().decode())
BEGIN:VEVENT
SUMMARY:Morning ride with the team.
DTSTART:20260328T070000Z
DTEND:20260328T133000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
ATTENDEE:mailto:me@example.com
ATTENDEE:mailto:another_friend@example.com
END:VEVENT

You can see that both attendees were added to the event, along with the custom start and end timestamps.

You can also update the list of attendees after you created the event to add new attendees.

>>> ride_event.attendees.append(vCalAddress("mailto:late_joiner@example.com"))

Lastly, add this event to the same calendar you created in the beginning.

>>> calendar.add_component(ride_event)

Now print the calendar to view everything you've added so far, this should include the calendar component with two events.

>>> print(calendar.to_ical().decode())
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//icalendar//example.com//EN
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
BEGIN:VEVENT
SUMMARY:Pick up bicycle from the workshop.
DTSTART:20260321T063000Z
DTEND:20260321T073000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT
BEGIN:VEVENT
SUMMARY:Morning ride with the team.
DTSTART:20260328T070000Z
DTEND:20260328T133000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
ATTENDEE:mailto:me@example.com
ATTENDEE:mailto:another_friend@example.com
ATTENDEE:mailto:late_joiner@example.com
END:VEVENT
END:VCALENDAR

Creating an .ics file

Now that you have finished creating your calendar, you can write it to a file.

>>> from pathlib import Path
>>> path = Path("example.ics")
>>> path.write_bytes(calendar.to_ical())
611

This creates a new file called example.ics and writes the bytes object returned by to_ical() to the file.

Look on your file system for the file, local to where you issued commands. Its contents should be the following.

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//icalendar//example.com//EN
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
BEGIN:VEVENT
SUMMARY:Pick up bicycle from the workshop.
DTSTART:20260321T063000Z
DTEND:20260321T073000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VEVENT
BEGIN:VEVENT
SUMMARY:Morning ride with the team.
DTSTART:20260328T070000Z
DTEND:20260328T133000Z
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
ATTENDEE:mailto:me@example.com
ATTENDEE:mailto:another_friend@example.com
ATTENDEE:mailto:late_joiner@example.com
END:VEVENT
END:VCALENDAR