caldav

library3.2.1pypypi✓ verified 86d ago

caldav is a Python client library for the CalDAV (RFC4791) protocol, enabling interaction with CalDAV servers to manage calendars, events, and tasks. Version 3.1.0 focuses on robustness, improved async support, and enhanced multi-server capabilities. The library maintains an active development cycle, frequently releasing bug fixes and server compatibility improvements, with major releases occurring every few years and minor releases more often.

http-networking

pip install caldav

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · CALDAV

caldav

http-networkingpythonv3.2.1

Install

5.0s avg

Import

1193ms

Disk

66MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.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

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 1.234s · 67.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 5.0s · import 1.151s · 67MB

66MB installed

● package 66MB

Code

Verified usage

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

DAVClient

✓ from caldav.davclient import DAVClient

AsyncDAVClient

✓ from caldav.davclient import AsyncDAVClient

Calendar

✓ from caldav.objects import Calendar

Event

✓ from caldav.objects import Event

This quickstart demonstrates how to connect to a CalDAV server, authenticate, retrieve the user's principal, list available calendars, and fetch the first event from each calendar. Credentials can be provided directly or via environment variables for security.

import os from caldav.davclient import DAVClient # Replace with your CalDAV server details or use environment variables CALDAV_URL = os.environ.get('CALDAV_URL', 'http://localhost:8008/dav.php/') CALDAV_USER = os.environ.get('CALDAV_USER', 'user1') CALDAV_PASS = os.environ.get('CALDAV_PASS', 'user1') def get_calendars_sync(): print(f"Connecting to CalDAV server at {CALDAV_URL} as {CALDAV_USER}") try: with DAVClient(url=CALDAV_URL, username=CALDAV_USER, password=CALDAV_PASS) as client: # Get the principal (user's root DAV resource) principal = client.principal() print(f"Connected to principal: {principal.url}") # Get all calendars for the principal calendars = principal.calendars() if not calendars: print("No calendars found.") return print(f"Found {len(calendars)} calendar(s):") for calendar in calendars: print(f"- {calendar.name} (URL: {calendar.url})") # Example: Fetch first event from the first calendar (if any) events = calendar.events() if events: event = events[0] print(f" First event: {event.summary} (UID: {event.uid})") else: print(" No events found in this calendar.") except Exception as e: print(f"An error occurred: {e}") if __name__ == "__main__": get_calendars_sync()

Debug

Known issues

breakingVersion 3.0.0 introduced 'massive code changes' and internal refactoring (e.g., transition from Black to Ruff, sans-io design concepts), despite claims of backward compatibility. Users upgrading from 2.x should thoroughly test their applications.

fix

Review the official changelog for specific changes. Test your application thoroughly against the new version, especially if relying on intricate internal behaviors or less common APIs. Consider migrating gradually if in production.

affects: 2.x -> 3.0.0+

gotchaAsync support was significantly refined and fixed in v3.1.0, indicating potential instability or non-intuitive usage patterns in earlier 3.x versions due to identified 'gaps' in the 'sans-io' design concept.

fix

Upgrade to `caldav` v3.1.0 or later for the most stable async experience. Ensure you are correctly `await`ing all asynchronous calls and consulting the latest async examples in the documentation.

affects: 3.0.0 - 3.0.2

gotchaThe `niquests` dependency fluctuated in 2.x versions (e.g., introduced, removed, re-introduced), which could lead to `ModuleNotFoundError` or unexpected behavior depending on the exact minor version installed.

fix

For 2.x versions, explicitly install the `niquests` package (`pip install niquests`) if experiencing import errors, or upgrade to a 3.x version where `httpx` is the primary HTTP client.

affects: 2.1.0 - 2.2.6

gotchaAs of v3.1.0, the `get_calendars()` method can now span multiple configuration file sections and use glob/wildcard expansion to aggregate calendars from multiple servers into a single `CalendarCollection`. This is an enhancement, but existing code might make assumptions about single-server behavior.

fix

If you relied on specific behavior of `get_calendars()` in a multi-server context or if your code parses the results assuming a single source, review your implementation to ensure compatibility with the new aggregation capabilities.

affects: 3.1.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'caldav'

The `caldav` package is not installed in your current Python environment.

fix

Install the package using pip: `pip install caldav`.

TypeError: 'NoneType' object is not subscriptable

This typically occurs when trying to access elements (e.g., `events()[0]`) of a list-like object (like `calendar.events()`) that has returned `None` or an empty list, meaning no items were found.

fix

Always check if the result of a method call (e.g., `principal.calendars()`, `calendar.events()`) is not empty before attempting to access its elements. For example: `events = calendar.events(); if events: first_event = events[0]`.

httpx.ConnectError: [Errno 111] Connection refused

The CalDAV server could not be reached or refused the connection. This can be due to incorrect URL, server being down, firewall issues, or incorrect port.

fix

Verify the `CALDAV_URL` is correct and accessible. Ensure the CalDAV server is running and not blocked by a firewall. Check if the port (e.g., 8008, 443) is correct and open.

TypeError: object AsyncDAVClient can't be used in 'await' expression (or similar async errors)

You are attempting to use an `AsyncDAVClient` method (or object) in an asynchronous context without correctly using `await`, or your async setup is incorrect.

fix

Ensure all methods of `AsyncDAVClient` and its derived objects (like `principal.calendars()`, `calendar.events()`) are properly `await`ed. Your code must be run within an `async def` function and executed using an async event loop (e.g., `asyncio.run()`).

Upgrade

Version history

3.2.1latest on PyPI · released May 28, 2026

Audit

Dependencies

clickrequiredCommand-line interface tools.

httpxrequiredHTTP client for network requests.

icalendarrequirediCalendar format parsing and generation.

lxmlrequiredXML parsing for DAV operations.

python-dateutilrequiredExtensions to the standard datetime module.

pydanticoptionalData validation and settings management (optional for some features).

Agent activity