Config file format#

The caldav.davclient.get_davclient(), caldav.davclient.get_calendar(), and caldav.davclient.get_calendars() functions read connection parameters from a config file. The file is searched in the following locations (first match wins):

  • $HOME/.config/caldav/calendar.conf

  • $HOME/.config/caldav/calendar.yaml

  • $HOME/.config/caldav/calendar.json

  • $HOME/.config/calendar.conf

  • /etc/caldav/calendar.conf

  • /etc/calendar.conf

The config file must be valid JSON or YAML. The path can also be given explicitly via the CALDAV_CONFIG_FILE environment variable.

Sections#

The file is divided into named sections. Each section contains key/value pairs describing how to connect to a CalDAV server and optionally which calendar to select. The section to use is chosen as follows (first match wins):

  1. The config_section parameter passed to get_davclient() / get_calendars().

  2. The CALDAV_CONFIG_SECTION environment variable.

  3. The default section.

Connection parameters#

All keys starting with caldav_ are connection parameters passed to the DAVClient constructor after stripping the prefix. The most common ones are:

Config key

DAVClient parameter

Notes

caldav_url

url

CalDAV server URL

caldav_username or caldav_user

username

Login name

caldav_password or caldav_pass

password

Login password

caldav_proxy

proxy

HTTP/HTTPS proxy URL

caldav_timeout

timeout

Request timeout in seconds

caldav_ssl_verify_cert

ssl_verify_cert

false to skip TLS verification

The special features key (not prefixed with caldav_) names a server-compatibility profile — e.g. xandikos, radicale, baikal. See caldav.compatibility_hints for the full list of known profiles.

Environment variable expansion#

Values may reference environment variables using ${VAR} or ${VAR:-default} syntax:

default:
    caldav_url: https://caldav.example.com/
    caldav_username: ${CALDAV_USER:-alice}
    caldav_password: ${CALDAV_PASSWORD}

Calendar parameters#

get_calendar() and get_calendars() accept calendar_name and calendar_url to select a specific calendar. These can also be set in a config section so that a named section always refers to one particular calendar:

work_inbox:
    caldav_url: https://caldav.example.com/
    caldav_username: alice
    caldav_password: secret
    calendar_name: Inbox

work_team:
    caldav_url: https://caldav.example.com/
    caldav_username: alice
    caldav_password: secret
    calendar_url: https://caldav.example.com/cal/shared/

Calling get_calendars(config_section="work_inbox") will return only the calendar named Inbox on that server.

Section inheritance#

A section may declare inherits: <other_section> to copy all values from another section and then override specific keys. This is useful when several sections share the same server or credentials:

base_work:
    caldav_url: https://caldav.example.com/
    caldav_username: alice
    caldav_password: secret

work_inbox:
    inherits: base_work
    calendar_name: Inbox

work_tasks:
    inherits: base_work
    calendar_name: Tasks

Inheritance is recursive: a section can inherit from a section that itself inherits from another.

Meta-sections (collections)#

A section with a contains key is a meta-section: it groups other sections together. get_calendars() with a meta-section will aggregate calendars from all listed sections, including across multiple servers:

personal:
    caldav_url: https://personal.example.com/
    caldav_username: alice
    caldav_password: secret1

work:
    caldav_url: https://work.example.com/
    caldav_username: alice
    caldav_password: secret2

all:
    contains:
        - personal
        - work

Calling get_calendars(config_section="all") returns calendars from both servers. Meta-sections are resolved recursively, so a meta-section may contain other meta-sections. Circular references are detected and ignored.

A section can also be disabled so it is skipped during expansion:

old_server:
    disable: true
    caldav_url: https://old.example.com/

Glob patterns and wildcards#

Instead of listing sections explicitly, contains may use glob patterns, and the config_section argument (or CALDAV_CONFIG_SECTION) itself may be a glob or *:

work_inbox:
    caldav_url: https://work.example.com/
    caldav_username: alice
    caldav_password: secret
    calendar_name: Inbox

work_tasks:
    caldav_url: https://work.example.com/
    caldav_username: alice
    caldav_password: secret
    calendar_name: Tasks

all_work:
    contains:
        - work_*

get_calendars(config_section="work_*") and get_calendars(config_section="all_work") are therefore equivalent. get_calendars(config_section="*") returns calendars from every non-disabled section in the file.

Environment variables#

Connection parameters can also be passed via environment variables without a config file. The variables are mapped as follows:

Environment variable

Parameter

CALDAV_URL

url

CALDAV_USERNAME or CALDAV_USER

username

CALDAV_PASSWORD or CALDAV_PASS

password

CALDAV_CONFIG_FILE

Path to config file

CALDAV_CONFIG_SECTION

Section name (may be a glob)

Examples#

Minimal single-server config#

---
default:
    caldav_url: https://caldav.example.com/dav/
    caldav_username: alice
    caldav_password: secret

Multiple servers aggregated under one name#

---
personal:
    caldav_url: https://personal.example.com/
    caldav_username: alice
    caldav_password: secret1
    features: xandikos

work:
    caldav_url: https://work.example.com/
    caldav_username: alice.work
    caldav_password: secret2

all:
    contains:
        - personal
        - work

Shared base with per-calendar overrides#

---
_server: &server
    caldav_url: https://caldav.example.com/
    caldav_username: alice
    caldav_password: secret

inbox:
    inherits: _server
    calendar_name: Inbox

tasks:
    inherits: _server
    calendar_name: Tasks
    calendar_url: https://caldav.example.com/cal/tasks/

Testing server compatibility#

The caldav-server-tester companion tool probes a CalDAV server and reports which features and RFC requirements it supports, which ones it handles in a quirky way, and which ones it gets wrong. Its output can be used to populate the features key in your config file so the caldav library applies the right workarounds automatically.

Installation:

pip install caldav-server-tester

Run against a config section defined in your calendar.conf:

caldav-server-tester --config-section myserver

Or supply connection details directly:

caldav-server-tester --caldav-url https://example.com/dav \
                     --caldav-username alice \
                     --caldav-password secret

The tool will run a series of checks and print which features deviate from the CalDAV standard. To get machine-readable output that you can paste into your calendar.conf, use --format yaml:

caldav-server-tester --config-section myserver --format yaml

Copy the features: block from the output into your config section. Alternatively, if your server matches one of the named profiles in caldav.compatibility_hints (e.g. radicale, baikal, xandikos), you can just name the profile:

myserver:
    caldav_url: https://example.com/dav
    caldav_username: alice
    caldav_password: secret
    features: radicale