Timezone-Aware Datetime: zoneinfo

By the end of this lesson you can:

• Tell the difference between a naive and an aware datetime.
• Create aware datetimes with zoneinfo.ZoneInfo and UTC.
• Convert a moment from one timezone to another with astimezone.
• Follow the golden rule: store UTC, display local.

A real story: a team schedules a "daily 8 a.m." report on a cloud server. It works in testing. In production it emails at 4 p.m. local time — because the server runs on UTC, and nobody said whose 8 a.m.

from datetime import datetime

now = datetime.now()          # "naive": no timezone attached
print(now)                    # 2026-05-28 14:30:00
# But 14:30 WHERE? On your laptop? The server? Python doesn't know.

Naive vs. aware

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

naive = datetime.now()                          # no tzinfo → naive
print(naive.tzinfo)                             # None

aware = datetime.now(ZoneInfo("Asia/Kuala_Lumpur"))
print(aware.tzinfo)                             # Asia/Kuala_Lumpur
print(aware)                                    # 2026-05-28 14:30:00+08:00

The +08:00 is the offset from UTC — that's what makes it unambiguous. zoneinfo is built into Python 3.9+ and knows every IANA timezone name ("Asia/Tokyo", "Europe/London", "America/New_York").

UTC: the universal reference

from datetime import datetime, timezone

# the RIGHT way to get "now" for storage:
now_utc = datetime.now(timezone.utc)
print(now_utc)                  # 2026-05-28 06:30:00+00:00

UTC (Coordinated Universal Time) is the world's reference clock — it has no daylight saving and never shifts. KL is always UTC+8; London is UTC+0 or +1 depending on the season. Store everything in UTC and you have one consistent timeline.

Converting between zones

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# a meeting at 9am New York time
ny = datetime(2026, 5, 28, 9, 0, tzinfo=ZoneInfo("America/New_York"))

# what time is that in KL and Tokyo?
print(ny.astimezone(ZoneInfo("Asia/Kuala_Lumpur")))  # 21:00 +08:00
print(ny.astimezone(ZoneInfo("Asia/Tokyo")))         # 22:00 +09:00
print(ny.astimezone(timezone.utc))                   # 13:00 +00:00

astimezone keeps the same instant but expresses it in a different zone's wall-clock time. 9 a.m. in New York is the same moment as 9 p.m. in KL — astimezone does the maths, including daylight saving.

The golden rule

Don't mix naive and aware

naive = datetime.now()
aware = datetime.now(timezone.utc)
# aware - naive  → TypeError! can't subtract across the divide

Python refuses to compare or subtract a naive and an aware datetime — it would be guessing. Keep your program all-aware (recommended) or all-naive, never mixed. To upgrade a naive one whose zone you know: naive.replace(tzinfo=ZoneInfo("Asia/Kuala_Lumpur")).

Formatting shows the offset

aware = datetime.now(ZoneInfo("Asia/Kuala_Lumpur"))
print(aware.strftime("%Y-%m-%d %H:%M %Z (%z)"))
# 2026-05-28 14:30 +08 (+0800)
print(aware.isoformat())     # 2026-05-28T14:30:00+08:00  ← great for APIs

Goal: given a job scheduled for "every day at 08:00 Asia/Kuala_Lumpur," answer "has it already run today?" correctly no matter what timezone the server is in — by always reasoning in the job's zone.

from datetime import datetime, time
from zoneinfo import ZoneInfo

JOB_ZONE = ZoneInfo("Asia/Kuala_Lumpur")
RUN_AT   = time(8, 0)        # 08:00 local to the job

def already_ran_today() -> bool:
    # "now" expressed in the JOB's timezone, not the server's
    now_local = datetime.now(JOB_ZONE)
    scheduled = datetime.combine(now_local.date(), RUN_AT, tzinfo=JOB_ZONE)
    return now_local >= scheduled

def next_run() -> datetime:
    now_local = datetime.now(JOB_ZONE)
    today_run = datetime.combine(now_local.date(), RUN_AT, tzinfo=JOB_ZONE)
    if now_local < today_run:
        return today_run
    from datetime import timedelta
    return today_run + timedelta(days=1)

print("Server thinks it's:", datetime.now().strftime("%H:%M"))
print("Job-zone time:     ", datetime.now(JOB_ZONE).strftime("%H:%M %Z"))
print("Already ran today? ", already_ran_today())
print("Next run (UTC):    ", next_run().astimezone(ZoneInfo("UTC")))

Server thinks it's: 06:30
Job-zone time:      14:30 +08
Already ran today?  True
Next run (UTC):     2026-05-29 00:00:00+00:00

Read the code

The whole bug class disappears because we never reason in the server's naive clock — every comparison happens in JOB_ZONE. datetime.combine stitches a date and a time into one aware datetime, and we convert the answer to UTC at the end for storage/logging. This is exactly the logic you'll lean on when scheduling real jobs in Lesson 35.

A naive datetime has no timezone, so it's ambiguous across machines; an aware one carries a tzinfo and points to a single global instant. Build aware datetimes with datetime.now(ZoneInfo("Area/City")) or datetime.now(timezone.utc), and move between zones with astimezone (same instant, different wall clock). Never mix naive and aware — Python won't let you. The golden rule: store UTC, display local. Get this right and scheduled, logged, and shared times work the same everywhere.