What this usually means
The root cause is almost always a mismatch between naive and aware datetime objects, or incorrect use of timezone libraries. Python's datetime module distinguishes between naive (no tzinfo) and aware (with tzinfo) objects. When you mix them in comparisons, arithmetic, or serialization, you get offset errors. Additionally, using pytz incorrectly (e.g., assigning tzinfo directly instead of calling localize()) can lead to wrong offsets, especially during DST transitions. The default datetime.timezone.utc is fine, but many developers rely on the system local timezone or pytz without understanding the pitfalls.
The first ten minutes — establish facts before touching code.
- 1Check if your datetime is aware: print(dt.tzinfo) — None means naive.
- 2View the full datetime representation: repr(dt) shows tzinfo details.
- 3Compare with UTC: print(dt.astimezone(datetime.timezone.utc)) — any shift indicates offset issue.
- 4Inspect the offset: print(dt.utcoffset()) — returns None for naive, timedelta for aware.
- 5If using pytz, verify you used localize() or normalize(), not direct assignment.
- 6Test across DST boundary: use a known date like 2024-03-10 (US spring-forward) to expose errors.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchAll lines where datetime objects are created: datetime.now(), datetime.utcnow(), datetime.fromtimestamp(), dateutil.parser.parse().
- searchAny explicit assignment to tzinfo attribute: dt.tzinfo = pytz.timezone('US/Eastern') (likely wrong).
- searchDatabase ORM model definitions: DateTimeField types and their timezone settings (e.g., timezone=True in SQLAlchemy).
- searchSerialization/deserialization code: JSON dumps with default=str or ISO format with .isoformat().
- searchThird-party API integrations: receiving or sending ISO 8601 strings with offset.
- searchTimezone conversion functions: calls to .replace(tzinfo=...) or .astimezone().
Practical causes, not theory. These are the things you will actually find.
- warningUsing datetime.utcnow() which returns a naive datetime; should use datetime.now(timezone.utc).
- warningDirectly assigning pytz timezone to tzinfo without localize(): dt = datetime(2024,3,10,2,30).replace(tzinfo=pytz.US/Eastern).
- warningMixing datetime objects from different sources: one from database (aware UTC), another from local code (naive).
- warningAccidental removal of tzinfo during formatting: .strftime() output loses tzinfo, and then parsed back as naive.
- warningUsing timezone-naive timestamps in a system that expects aware (e.g., Django with USE_TZ=True).
- warningRelying on system local timezone via datetime.now() without explicit timezone.
Concrete fix directions. Pick the one that matches your root cause.
- buildReplace datetime.utcnow() with datetime.now(timezone.utc).
- buildAlways use pytz's .localize() to attach timezone to a naive datetime: eastern = pytz.timezone('US/Eastern'); aware = eastern.localize(naive_dt).
- buildConvert all datetimes to UTC internally and only convert for display: store as aware UTC, then .astimezone() for output.
- buildUse dateutil.parser.parse(dt_str) which automatically parses offsets if present, or specify tzinfos argument.
- buildIn Django, set USE_TZ=True and ensure all DateTimeField values are aware; use django.utils.timezone.now().
- buildWhen comparing or subtracting, convert both to UTC first: dt1.astimezone(utc) - dt2.astimezone(utc).
A fix you cannot prove is a guess. Close the loop.
- verifiedPrint tzinfo before and after fix: assert dt.tzinfo is not None.
- verifiedCompare with a known UTC timestamp: datetime(2024,1,1,0,0,0,tzinfo=timezone.utc).
- verifiedRun a unit test that crosses a DST transition (e.g., 'America/New_York' on March 10, 2024 2:00 AM).
- verifiedVerify serialization round-trip: iso = dt.isoformat(); assert datetime.fromisoformat(iso) == dt (Python 3.7+).
- verifiedCheck database storage: value should have 'Z' or offset in string representation.
- verifiedUse breakpoint() or pdb to step through and inspect each datetime's tzinfo and utcoffset.
Things that make this bug worse or harder to find.
- warningNever use dt.replace(tzinfo=pytz.timezone(...)) — it doesn't adjust for DST.
- warningDon't ignore warnings: 'RuntimeWarning: DateTimeField received a naive datetime' is a red flag.
- warningAvoid storing timestamps as strings with offsets unless you control the format; prefer aware UTC.
- warningDon't assume fromisoformat() handles all offsets in older Python versions; it only works for fixed offsets in 3.7-3.10.
- warningNever compare local times directly between timezones without converting to a common tz.
- warningDon't mix pytz and zoneinfo (Python 3.9+) in the same project—pick one library.
The 3 AM Server Crash: A Daylight Saving Time Pitfall
Timeline
- 02:30Scheduled Celery task to update route ETAs fails with ValueError.
- 02:31PagerDuty alerts: 'Failed to compute delivery window for order 45231'.
- 02:35I check logs: 'TypeError: can't compare offset-naive and offset-aware datetimes'.
- 02:40Look at the route ETA calculation code: it subtracts current time from a stored UTC ETA.
- 02:45Find that current time uses datetime.now() (naive) while ETA is aware UTC from PostgreSQL.
- 02:50Quick fix: change datetime.now() to datetime.now(timezone.utc). Deploy hotfix.
- 02:55Monitor: all pending tasks complete successfully.
- 03:00Write unit test to catch future DST issues; add comment in code.
It was 2:30 AM on a Sunday, and I was half-asleep when my phone buzzed with a PagerDuty alert. Our delivery route optimization service was failing—every Celery task errored with a ValueError. The logs showed a TypeError about comparing offset-naive and offset-aware datetimes. I've seen this before, but usually in tests, not in production at 2 AM.
I pulled up the route ETA function. It computes the remaining time until the next delivery window: `eta = row['scheduled_time'] - datetime.now()`. The `scheduled_time` came from PostgreSQL as an aware UTC datetime (with tzinfo), but `datetime.now()` returned a naive local time. On most days, the comparison worked because the local offset happened to match UTC minus 5 hours, but on that day—daylight saving time had just ended—the local offset changed, causing a mismatch.
The fix was trivial: replace `datetime.now()` with `datetime.now(timezone.utc)`. I deployed the hotfix within 10 minutes. But the real lesson was that we had no unit tests for DST transitions. I added a test that simulates the 'spring forward' and 'fall back' scenarios. Also, I made a policy: all datetimes in the codebase must be aware UTC, and any user-facing times are converted at the display layer only.
Root cause
Using naive datetime.now() where an aware UTC datetime was expected, causing a comparison error that surfaced during a DST transition.
The fix
Replaced datetime.now() with datetime.now(timezone.utc); added unit tests for DST boundary conditions.
The lesson
Always store and compare datetimes as aware UTC; never rely on implicit timezone assumptions. Test across DST transitions.
Python's datetime module has two kinds of datetime objects: naive (no timezone info) and aware (with tzinfo). Naive objects are like plain wall-clock times—they don't specify which timezone they refer to. Aware objects include a tzinfo object that defines the UTC offset and timezone rules.
The distinction matters because arithmetic, comparisons, and formatting behave differently. For example, subtracting two naive datetimes gives a timedelta assuming they're in the same timezone. Subtracting two aware datetimes works correctly if they're in the same timezone, but you should convert to UTC first to avoid ambiguity. Comparing naive and aware raises TypeError.
Many standard library functions return naive datetimes by default: datetime.now(), datetime.utcnow(), datetime.fromtimestamp(). You must explicitly pass a tzinfo argument to get aware objects: datetime.now(timezone.utc).
The pytz library provides historical timezone data, but its API is tricky. A frequent mistake is directly assigning a pytz timezone to tzinfo: dt = datetime(2024,3,10,2,30).replace(tzinfo=pytz.timezone('US/Eastern')). This does not account for DST—it sets the offset to whatever the timezone's standard offset is, ignoring that March 10 is actually EDT (UTC-4) not EST (UTC-5).
The correct way is to use the localize() method: eastern = pytz.timezone('US/Eastern'); aware_dt = eastern.localize(naive_dt). This uses the timezone's rules to pick the correct offset for that datetime. For converting back to UTC or between timezones, use aware_dt.astimezone(pytz.utc) or normalize().
Python 3.9 introduced zoneinfo, which is part of the standard library and doesn't have pytz's pitfalls. If you can, migrate to zoneinfo and use its localize equivalent: dt.replace(tzinfo=ZoneInfo('America/New_York')) actually works correctly. But note: zoneinfo may not have historical data as extensive as pytz.
When you suspect an offset error, start by inspecting the datetime object in a REPL:
>>> import datetime
>>> dt = datetime.datetime.now()
>>> dt.tzinfo # None
>>> dt.utcoffset() # None
Now create an aware UTC datetime:
>>> utc_dt = datetime.datetime.now(datetime.timezone.utc)
>>> utc_dt.tzinfo # datetime.timezone.utc
>>> utc_dt.utcoffset() # datetime.timedelta(seconds=0)
To convert a naive datetime to aware, you can use pytz.localize or zoneinfo:
>>> import pytz
>>> eastern = pytz.timezone('US/Eastern')
>>> naive = datetime.datetime(2024, 3, 10, 2, 30)
>>> aware = eastern.localize(naive)
>>> aware.utcoffset() # timedelta(hours=-5) or -4 depending on DST
Check the ISO format: aware.isoformat() includes offset like '2024-03-10T02:30:00-05:00'.
When you store datetimes in a database, use aware UTC objects. SQLAlchemy with timezone=True column will store as UTC aware. Django with USE_TZ=True does the same. But if you accidentally pass a naive datetime, you get a warning or silent conversion that may shift times.
For JSON serialization, use .isoformat() to include offset, and parse with datetime.fromisoformat() (Python 3.7+). For older Python, use dateutil.parser.parse. Never call str(dt) directly—it may drop tzinfo info.
When receiving timestamps from external APIs, always parse them with attention to offset. If the string lacks offset, assume UTC only if documented. Otherwise, treat as suspect and reject or convert with explicit timezone.
Frequently asked questions
Why does datetime.utcnow() return a naive datetime?
For backward compatibility. datetime.utcnow() was designed to give the UTC time but without timezone info. Since Python 3.12, it's deprecated in favor of datetime.now(timezone.utc). The latter returns an aware datetime with tzinfo set to UTC.
How do I fix 'can't compare offset-naive and offset-aware datetimes'?
Convert both to the same type. Either make the naive datetime aware (e.g., replace(tzinfo=timezone.utc) if you know it's UTC) or convert the aware datetime to naive using .replace(tzinfo=None)—but be careful: the latter discards timezone info. The safest is to make both aware UTC.
What is the difference between pytz and zoneinfo?
pytz is a third-party library with historical timezone data going back to 1900. It requires localize/normalize to handle DST correctly. zoneinfo is the standard library module since Python 3.9, using IANA timezone data from the OS. For fixed offsets, both work; for DST, zoneinfo's tzinfo assignment works correctly without extra steps. zoneinfo is preferred for new projects on Python 3.9+.
Why does my datetime shift by an hour when I store it?
Likely because the datetime is naive and the database or ORM interprets it as local time and converts to UTC. For example, PostgreSQL's timestamp without time zone stores as-is, while timestamp with time zone converts to UTC. If you send a naive datetime, the driver may assume local time. Solution: always store aware UTC datetimes.
How do I get the current time in a specific timezone?
Use datetime.now(timezone_object). For example, to get current time in US/Eastern: import pytz; tz = pytz.timezone('US/Eastern'); now = datetime.now(tz). For zoneinfo: from zoneinfo import ZoneInfo; now = datetime.now(ZoneInfo('America/New_York')).