Outlook CalDAV Sync

A Python tool to sync calendar events from an Outlook JSON export to a CalDAV server (e.g. Nextcloud Calendar, Radicale, Baikal).

Overview

Outlook does not speak CalDAV natively. If you need your Outlook calendar available in a CalDAV-based application — whether for privacy, interoperability, or self-hosting reasons — the usual path involves manual exports or fragile third-party connectors.

This tool bridges that gap: it reads the JSON format that Microsoft's Power Automate (or a custom script) can export from an Outlook calendar and pushes the events to any CalDAV-compatible server. Only events that have actually changed are uploaded, keeping the sync efficient. Events that have disappeared from Outlook can optionally be removed from the CalDAV calendar as well.

Features

• Sync Outlook JSON calendar exports to any CalDAV server
• Skip unchanged events using SHA-256 hash comparison — only changed events are uploaded
• Configurable time window: how many days into the past and future to sync
• Filter events by Outlook category or subject regex — excluded events are also removed from the remote calendar
• Anonymize attendee e-mail addresses (replace domain with @invalid.invalid)
• Mark all synced events as CONFIDENTIAL (private) on the CalDAV side
• Dry-run mode: preview what would happen without making any changes
• Force-update mode: re-upload all events even if they appear unchanged
• Reset remote: wipe all events from the CalDAV calendar before a fresh sync
• Optional log file in addition to stdout

Install

Requires at least Python 3.12.

pip install outlook-caldav-sync

The command outlook-caldav-sync is then available. Run outlook-caldav-sync --help for a full list of options.

For development installs, use uv:

uv sync
uv run outlook-caldav-sync --help

Outlook JSON export

The tool expects a JSON file containing an array of calendar event objects in the format that Microsoft Power Automate produces when reading from the Outlook calendar connector. Each event object should contain at least the following fields:

Configuration

Configuration is provided as a JSON file passed via --config. Example (config.json):

{
  dav_url: "https://nextcloud.example.com/remote.php/dav/",
  dav_calendar: "my-calendar-id",
  dav_username: "myuser",
  dav_password: "secret",
  dav_past_days: 3,
  dav_future_days: 400,
  log_file: "/var/log/outlook-caldav-sync.log",
  anonymize_email: true,
  private: false,
  delete_missing: true,
  nosync_categories: ["Reminder/Blocker"],
  nosync_subject_regex: ["^Declined:"],
  nosync_showas: ["free"]
}

Usage

outlook-caldav-sync -c config.json -i calendar-export.json

Full list of CLI options:

Filtering / no-sync

Events can be excluded from syncing in two ways:

• By category: add Outlook category names to nosync_categories. Events with those categories are skipped during upload and removed from the remote if they exist there.
• By subject regex: add regular expressions to nosync_subject_regex. Events whose subject matches any pattern are treated the same way.
• By showAs value: add Outlook showAs values to nosync_showas. Known values include free, busy, oof, tentative. Events matching are skipped and removed from the remote.

This is useful for blocking personal reminders, declined meetings, or any category you do not want mirrored to your CalDAV calendar.

Logging

The tool logs to stdout by default. Set log_file in the config to additionally write to a file (append mode). Use -vv / --debug to enable verbose DEBUG output.

Contribute and Development

Contributions are welcome! The development is easiest with uv: uv sync installs all dependencies and uv run outlook-caldav-sync runs the tool directly.

Run the test suite with uv run pytest, linting with uv run ruff check, and type checking with uv run ty check.

License

Apache-2.0, Copyright Max Mehl. See LICENSE for details.