The CalDAV integration allows you to connect your WebDAV calendar to Home Assistant as one of these entity types:
- A calendar entity which can be used to trigger automations based on the the start or end of an event using criteria such as the event name or description.
- A todo entity which tracks the number of active items on the to-do list.
The WebDAV entities are updated roughly every 15 minutes.
To add the CalDAV integration to your Home Assistant instance, use this My button:
If the above My button doesn’t work, you can also perform the following steps manually:
During the configuraiton flow you will be asked for the CalDAV server and credentials
for it. An example CalDAV URL is
You may also manually add a WebDAV calendar in Home Assistant by adding the following section to your
configuration.yaml file. This method does not support to-do lists.
# Example configuration.yaml entry for nextcloud, calendars will be found automatically calendar: - platform: caldav username: john.doe password: !secret caldav url: https://nextcloud.example.com/remote.php/dav
# Example configuration.yaml entry for Radicale, calendars will be found automatically calendar: - platform: caldav username: john.doe password: !secret caldav url: https://radicale.example.com/
# Example configuration.yaml entry for iCloud, calendars will be found automatically calendar: - platform: caldav username: !secret userIcloud password: !secret passIcloud url: https://caldav.icloud.com
All day events are not supported by default when configured using yaml.
The examples below create calendar entities that match specific search criteria.
# Example configuration.yaml entry calendar: - platform: caldav username: [email protected] password: !secret caldav url: https://baikal.my-server.net/cal.php/calendars/[email protected]/default custom_calendars: - name: "HomeOffice" calendar: "Agenda" search: "HomeOffice" - name: "WarmupFlat" calendar: "Agenda" search: "Warmup"
This will create two entities for the calendar name Agenda: “HomeOffice” and “WarmupFlat” with events matching the regular expression specified in
search. In custom calendars, events that last a whole day are taken into account.
Please note that if you use the
custom_calendars option, only those calendars will be loaded. You cannot use
custom_calendars in the same configuration.
List of the calendars to filter. Empty or absent means no filtering, i.e., all calendars will be added. It cannot be used if
custom_calender option is used.
Details on any custom calendars you want to create. Using this will only load the custom calendars supplied. No other calendars will load.
Individual Calendar Events can power automations such as:
- Turn on a light at the start of the event named Front Yard Light
- Send a notification 5 minutes before the start of any event
- Stop the media player 30 minutes after the end of the event named Exercise.
See Calendar Automations for an overview, and read more about Calendar Trigger Variables for the available information you can use in a condition or action such as the event
location and more.
The calendar entity has additional attributes related to a single next upcoming event.
Using the entity state and attributes is more error prone and less flexible than using Calendar Automations. The calendar entity itself may only track a single upcoming active event and can’t handle multiple events with the same start time, or overlapping events.
offset_reached: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting
!! -10would trigger this attribute to be on 10 minutes before the event starts. This should be in the format of
MM. This attribute is not available when configured from the UI.
True/Falseif this is an all day event. Will be
Falseif there is no event found.
message: The event title with the
searchvalues extracted. So in the above example for
offset_reachedthe message would be set to Very important meeting
- description: The event description.
- location: The event Location.
- start_time: Start time of event.
- end_time: End time of event.
The todo entity is the number of incomplete items on the to-do list. See the todo integration documentation for details and available services that can be used in automations.
You might need some additional system packages to compile the Python CalDAV library. On a Debian based system, install them by:
sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
You may be required to use app specific passwords to generate a new password for use by Home Assistant to avoid sharing your iCloud account password.