PyInns - Home

Timezones are one of the trickiest parts of working with dates and times in Python — especially when your app spans multiple regions, servers run in UTC, or users expect local time. In 2026, Python’s built-in zoneinfo module (introduced in 3.9) is the recommended way to handle timezones accurately and portably, replacing older libraries like pytz in most cases.

Here’s a practical, step-by-step guide to working with timezones in Python — from basic conversions to production best practices.

1. The Two Types of datetime: Naive vs Aware

A naive datetime has no timezone info — just date/time numbers. A aware datetime knows its timezone (via tzinfo).


from datetime import datetime

# Naive (no timezone)
naive = datetime(2026, 3, 15, 14, 30)
print(naive)  # 2026-03-15 14:30:00

# Aware (with timezone)
from zoneinfo import ZoneInfo
aware = naive.replace(tzinfo=ZoneInfo("Asia/Karachi"))
print(aware)  # 2026-03-15 14:30:00+05:00

Rule 2026: Always use aware datetimes in production. Naive times lead to bugs during DST changes or cross-timezone calculations.

2. Converting Between Timezones

Use astimezone() to shift an aware datetime to another timezone.


from zoneinfo import ZoneInfo

dt_khi = datetime(2026, 3, 15, 14, 30, tzinfo=ZoneInfo("Asia/Karachi"))
dt_utc = dt_khi.astimezone(ZoneInfo("UTC"))
dt_ny = dt_khi.astimezone(ZoneInfo("America/New_York"))

print(dt_khi)  # 2026-03-15 14:30:00+05:00
print(dt_utc)  # 2026-03-15 09:30:00+00:00
print(dt_ny)   # 2026-03-15 09:30:00-05:00 (or -04:00 during DST)

3. Localizing Naive Datetimes (Important!)

Never attach tzinfo directly to a naive datetime — use localize() or replace carefully.


# Wrong way (can cause DST bugs)
wrong = naive.replace(tzinfo=ZoneInfo("Asia/Karachi"))

# Correct way
from zoneinfo import ZoneInfo
correct = naive.replace(tzinfo=ZoneInfo("Asia/Karachi"))
# or use localize() if you have pytz (legacy)

4. Working with UTC (Best Practice)

Store everything in UTC internally, convert to local only for display.


utc_now = datetime.now(ZoneInfo("UTC"))
print(utc_now)  # e.g. 2026-03-15 09:30:00+00:00

# Convert to user's timezone for display
user_tz = ZoneInfo("Asia/Karachi")
local_now = utc_now.astimezone(user_tz)
print(local_now)  # 2026-03-15 14:30:00+05:00

5. Legacy pytz vs Modern zoneinfo (2026 Recommendation)

pytz is still common but officially deprecated for new code. Use zoneinfo — it’s in the standard library and more accurate.


# Legacy pytz (avoid for new code)
import pytz
dt = datetime(2026, 3, 15, 14, 30)
dt_pacific = pytz.timezone("US/Pacific").localize(dt)

Tip: If supporting Python < 3.9, use backports.zoneinfo package.

Common Pitfalls & Best Practices

Never use datetime.now() without tzinfo — use datetime.now(ZoneInfo("UTC"))
Avoid mixing naive and aware datetimes — always convert
Handle DST carefully — zoneinfo does this correctly
Store timestamps in UTC in databases
Use pendulum library if you want even simpler timezone handling

Conclusion

Timezones in Python can be tricky, but in 2026 the tools are excellent: zoneinfo for standard compliance, pendulum for simplicity, and aware datetimes everywhere. Master these concepts, and your applications will handle global users, logs, schedules, and real-time data correctly — without the usual timezone nightmares.

Next time you see a timestamp, make it aware, store it in UTC, and convert for display — your users and your future self will thank you.

TimeDelta - Time Travel with timedelta