zoneinfo

import zoneinfo

The zoneinfo module provides a concrete implementation of datetime.tzinfo for working with the IANA time zone database. Added in Python 3.9 (PEP 615), it handles daylight saving time transitions automatically and supports the fold attribute for handling ambiguous times during transitions.

By default, zoneinfo uses the system’s time zone data. If no system data is available, it falls back to the tzdata package from PyPI.

The ZoneInfo Class

ZoneInfo(key)

The primary constructor takes an IANA time zone key and returns a tzinfo object:

from zoneinfo import ZoneInfo
from datetime import datetime

# Create a datetime with a specific timezone
dt = datetime(2024, 7, 15, 14, 30, tzinfo=ZoneInfo("America/New_York"))
print(dt)
# 2024-07-15 14:30:00-04:00

print(dt.tzname())
# EDT

Parameters:

Parameter	Type	Default	Description
key	str	—	IANA time zone name (e.g., “America/Los_Angeles”)

Raises: ZoneKeyNotFoundError if the time zone key is not found.

The constructor returns the same object for a given key (cached):

from zoneinfo import ZoneInfo

a = ZoneInfo("Europe/Berlin")
b = ZoneInfo("Europe/Berlin")
print(a is b)
# True

ZoneInfo.no_cache(key)

Returns a new object each time, bypassing the cache:

from zoneinfo import ZoneInfo

a = ZoneInfo.no_cache("America/Chicago")
b = ZoneInfo.no_cache("America/Chicago")
print(a is b)
# False

ZoneInfo.clear_cache()

Invalidates the cache:

from zoneinfo import ZoneInfo

ZoneInfo.clear_cache()  # Clear all
ZoneInfo.clear_cache(only_keys=["America/New_York"])  # Specific keys

ZoneInfo.key

Read-only attribute returning the IANA key:

from zoneinfo import ZoneInfo

zi = ZoneInfo("Asia/Tokyo")
print(zi.key)
# Asia/Tokyo

Module Functions

available_timezones()

Returns all valid IANA time zone keys:

from zoneinfo import available_timezones

timezones = available_timezones()
print("America/New_York" in timezones)
# True

reset_tzpath()

Sets or resets the time zone search path:

from zoneinfo import reset_tzpath, TZPATH

print(TZPATH)
# ('/usr/share/zoneinfo',)

reset_tzpath(("/custom/path",))

Working with Datetimes

datetime.astimezone()

Convert a naive datetime to an aware datetime:

from zoneinfo import ZoneInfo
from datetime import datetime

naive = datetime(2024, 3, 10, 10, 0)
aware = naive.astimezone(ZoneInfo("America/New_York"))
print(aware)
# 2024-03-10 10:00:00-05:00

DST is handled automatically:

from zoneinfo import ZoneInfo
from datetime import datetime, timedelta

dt = datetime(2024, 7, 15, 10, tzinfo=ZoneInfo("America/New_York"))
print(dt.tzname())
# EDT

dt_winter = dt + timedelta(days=180)
print(dt_winter.tzname())
# EST

Common Patterns

UTC Conversion

from zoneinfo import ZoneInfo
from datetime import datetime

now_utc = datetime.now(ZoneInfo("UTC"))
print(now_utc)

local = datetime(2024, 7, 15, 14, 30)
utc = local.astimezone(ZoneInfo("UTC"))
print(utc)

Multiple Timezones

from zoneinfo import ZoneInfo
from datetime import datetime

meeting = datetime(2024, 7, 15, 14, 0, tzinfo=ZoneInfo("America/New_York"))

print(meeting.astimezone(ZoneInfo("Europe/London")))
# 2024-07-15 19:00:00+01:00

print(meeting.astimezone(ZoneInfo("Asia/Tokyo")))
# 2024-07-16 03:00:00+09:00

Exceptions

ZoneKeyNotFoundError

Raised when a time zone key cannot be found:

from zoneinfo import ZoneInfo, ZoneKeyNotFoundError

try:
    zi = ZoneInfo("Invalid/Timezone")
except ZoneKeyNotFoundError as e:
    print(f"Time zone not found: {e}")
# Time zone not found: 'Invalid/Timezone'

See Also

• sys
• platform
• inspect