datetime, zoneinfo & time

Store instants in UTC with timezone-aware datetime. Convert for display with zoneinfo (tzdata on Windows via tzdata package). Use timedelta for durations, not integer seconds alone.

Recipe

from datetime import datetime, timezone
from zoneinfo import ZoneInfo
 
utc_now = datetime.now(timezone.utc)
local = utc_now.astimezone(ZoneInfo("America/New_York"))
print(utc_now.isoformat(), local.isoformat())

When to reach for this:

• API timestamps (always UTC ISO-8601)
• User-local display formatting
• Scheduling across DST boundaries
• Measuring elapsed time (monotonic for perf)
• Parsing ISO strings from JSON

Working Example

from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo
 
def next_billing(from_utc: datetime, days: int) -> datetime:
    if from_utc.tzinfo is None:
        raise ValueError("aware datetime required")
    return from_utc + timedelta(days=days)
 
def format_for_user(instant_utc: datetime, tz_name: str) -> str:
    tz = ZoneInfo(tz_name)
    return instant_utc.astimezone(tz).strftime("%Y-%m-%d %H:%M %Z")
 
start = datetime(2026, 7, 9, 12, 0, tzinfo=timezone.utc)
due = next_billing(start, 30)
print(format_for_user(due, "Europe/Berlin"))

What this demonstrates:

• Reject naive datetimes in domain functions
• Arithmetic with timedelta preserves awareness
• ZoneInfo IANA names for correct DST
• strftime for display only - store ISO in data

Deep Dive

Aware vs Naive

Perf timing

• time.perf_counter() for benchmarks
• Not datetime.now for durations

Gotchas

• Naive now() comparisons - DST bugs. Fix: datetime.now(timezone.utc).
• Integer epoch everywhere - loses subsecond and tz context. Fix: datetime in models, epoch at boundary if needed.
• zoneinfo missing on Windows - install tzdata PyPI. Fix: document in deployment.
• Parsing ambiguous local times - DST fold. Fix: store UTC; convert on display only.
• strftime %Z misleading - abbreviations ambiguous. Fix: include offset %z in APIs.

Alternatives

FAQs

Related

• json & Serialization - ISO in JSON
• Standard Library Overview - map
• hashlib, secrets & uuid - time-based ids (uuid1 caution)
• Standard Library Best Practices - time rules

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.