Timezones

Default behavior

By default, ics-query uses each component’s own timezone when comparing against your query.

Two events at 6am — one in Berlin, one in Los Angeles — both match a query for a given date, even though they are hours apart in absolute time. Each event is compared against your query in its own local time.

Querying in a specific timezone

Use --tz to convert all components to the same timezone before comparing:

ics-query at --tz=Europe/Berlin 2024-08-20 calendar.ics -

With --tz set, the same two 6am events behave differently. The Los Angeles event at 6am is 3pm in Berlin. If you query for August 20th in Berlin time, only the Berlin event matches — unless the LA event also overlaps that date in Berlin time.

Use --tz=localtime to query in your system timezone:

ics-query at --tz=localtime 2024-08-20 calendar.ics -

Use --tz=UTC for UTC:

ics-query at --tz=UTC 2024-08-20 calendar.ics -

Set the timezone via environment variable instead of passing the flag each time:

export ICS_QUERY_TZ=Europe/Berlin
ics-query at 2024-08-20 calendar.ics -

Available timezones

ics-query uses Python’s zoneinfo module for timezone data. To list all available names:

ics-query --available-timezones

The output includes localtime (your system timezone), UTC, and all IANA timezone names such as Europe/Berlin, America/New_York, Asia/Tokyo.

Floating times

Some calendar events have no timezone at all — they use floating times. A floating time of 9am means 9am wherever you are, with no timezone attached.

When you query without --tz, floating times are matched against your query as-is. When you use --tz, floating times are treated as if they are in the specified timezone.

X-WR-TIMEZONE

Some calendar applications export calendars with an X-WR-TIMEZONE property instead of individual TZID attributes on each component. ics-query handles this automatically via the x-wr-timezone library.