A local date and time does not always identify one instant. Daylight-saving transitions can repeat or skip wall-clock values. Standard-library zoneinfo applies historical rules through IANA names such as America/New_York.
from datetime import UTC, datetime
from zoneinfo import ZoneInfo
now_utc = datetime.now(UTC)
new_york = now_utc.astimezone(ZoneInfo("America/New_York"))
london = now_utc.astimezone(ZoneInfo("Europe/London"))Convert an instant with astimezone(). Do not mechanically replace tzinfo on a datetime that already represents another zone because that reinterprets rather than converts it.
Store occurred instants as aware UTC values. For “every day at 9 AM in London,” preserve the IANA zone too because its UTC offset can change. During repeated local times, fold distinguishes the two occurrences. Validate ambiguous input for critical schedules.
The APScheduler guide shows why schedulers need an explicit timezone.
The official zoneinfo documentation, accessed July 22, 2026, covers IANA data, fold, and the tzdata fallback. Test actual transition dates for every supported business zone.
Instants and wall-clock values
An instant is one point on the global timeline; a wall-clock value is what people see in a region. An aware datetime has a tzinfo capable of determining its UTC offset. A naive value has tzinfo=None, so Python cannot know whether it means UTC, server time, or a user's local time. Require that context at system boundaries instead of guessing.
Use IANA identifiers such as America/Toronto, Europe/London, and Asia/Tokyo. Abbreviations such as CST are ambiguous, while a fixed offset cannot describe seasonal and historical rules. Validate identifiers received from clients:
from zoneinfo import ZoneInfoNotFoundError
def get_zone(name: str) -> ZoneInfo:
allowed = {"America/New_York", "Europe/London", "Asia/Tokyo"}
if name not in allowed:
raise ValueError("unsupported time zone")
try:
return ZoneInfo(name)
except ZoneInfoNotFoundError as exc:
raise RuntimeError("time zone data is unavailable") from excAn allowlist suits products with defined markets. If users can choose any zone, build the selector from zoneinfo.available_timezones() and reject values outside that set.
Convert instead of reinterpreting
astimezone() preserves the instant and changes its local representation. By contrast, replace(tzinfo=...) keeps the clock fields and assigns them a new meaning:
meeting_utc = datetime(2026, 10, 20, 15, 0, tzinfo=UTC)
meeting_ny = meeting_utc.astimezone(ZoneInfo("America/New_York"))
## This means 15:00 on New York's clock; it is not a conversion.
different_instant = meeting_utc.replace(
tzinfo=ZoneInfo("America/New_York")
)Attaching a zone with replace() can be correct when trusted input explicitly represents local time and another field supplies the zone. It is not correct for changing the display zone of an existing instant.
Handle gaps, overlaps, and fold
When clocks move forward, some local values do not exist. When clocks move backward, an interval occurs twice. PEP 495 introduced fold: zero chooses the offset before the backward transition and one chooses the offset after it.
zone = ZoneInfo("America/New_York")
first = datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=0)
second = datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=1)
assert first.timestamp() != second.timestamp()Constructing a value with ZoneInfo does not automatically reject nonexistent or ambiguous local input. For bookings, payroll cutoffs, and medical reminders, make the policy explicit: ask which occurrence is intended, shift according to a documented rule, or reject the value. One validation technique converts a candidate to UTC and back, then compares its clock fields and fold.
Store enough information
Store occurred instants as aware UTC values or an unambiguous epoch representation, then convert only for display. APIs should normally emit ISO 8601 timestamps containing Z or a numeric offset.
Future civil schedules need different data. For “weekdays at 09:00 in London,” retain the local time and the IANA zone. Turning the first occurrence into UTC and adding 24 hours can make the event appear at 08:00 or 10:00 after a transition. A fixed offset cannot follow rule changes.
local_start = 09:00
time_zone = Europe/London
recurrence = weekdaysResolve each occurrence with the rules available when the schedule is calculated. Where legal or financial reproducibility matters, also save the resolved UTC instant and define whether updated time-zone data changes occurrences already generated.
Parse and serialize deliberately
datetime.fromisoformat() parses an offset-bearing timestamp, but an offset is not an IANA zone. If an API receives a local value and zone separately, validate both:
local = datetime.fromisoformat("2026-12-03T09:00:00")
if local.tzinfo is not None:
raise ValueError("expected local time without offset")
aware = local.replace(tzinfo=get_zone("Europe/London"))
instant = aware.astimezone(UTC)Use isoformat() for interoperable output and do not strip the offset for convenience. UTC makes logs easier to correlate; retaining the original zone lets the interface show the date and label users expect.
Ship and update the database
zoneinfo first searches the operating system database and then the first-party tzdata package. Some Windows installations and minimal containers lack IANA data. Add tzdata when deployment cannot guarantee it, and exercise a representative lookup in a health check.
ZoneInfo objects are cached. Changing the database beneath a running process does not guarantee existing objects use the new rules. After a system or tzdata update, restart the application normally and regression-test affected schedules.
Test transition boundaries
Tests using only ordinary January dates miss difficult behavior. Include a forward gap, a backward overlap, a region without seasonal changes, and zones whose transitions occur on different dates. Assert UTC instants rather than abbreviations:
def test_overlap_represents_two_instants():
zone = ZoneInfo("America/New_York")
a = datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=0)
b = datetime(2026, 11, 1, 1, 30, tzinfo=zone, fold=1)
assert b.timestamp() - a.timestamp() == 3600Governments can change rules, so do not encode today's offset as a permanent assumption. Tests verify business policy for chosen dates, while dependency maintenance keeps the data current.
Before release, confirm that every input is classified as an instant or local value, UTC values are aware, conversions use astimezone(), and future civil events retain an IANA identifier. Document policies for gaps and overlaps, provide tzdata where needed, and test real transition dates.
The PEP 495 specification, accessed July 28, 2026, explains ambiguous local times and fold.
Review an end-to-end flow
Consider a meeting form with 2026-11-01 01:30 and America/New_York. The controller first validates the exact input format and allowed zone. The domain layer notices that the clock value occurs twice and asks for the intended occurrence rather than selecting silently. After that choice, it creates an aware value, converts it to UTC, and saves both the instant and original IANA name. Responses carry an offset-bearing timestamp, while the interface converts from the saved instant to the viewer's selected zone.
This flow also prevents a common mistake: applying the server's local zone because the client omitted one. Rejecting incomplete data is more reliable than making the result depend on where a container happens to run.
For recurring events, test generation rather than only the first occurrence. Generate dates across at least one transition and verify local clock time, UTC instant, and fold policy. If the product lets a user change zones, define whether that means “same instant, different display” or “same local time in a new region”; those are different operations.
Operational monitoring should use UTC instants in structured logs and include the relevant IANA name as a separate field. When investigating a discrepancy, record the application version and installed tzdata version. This evidence distinguishes a conversion defect from an intentional database-rule update.