How do datetime.astimezone(tz) and datetime.replace(tzinfo=tz) differ?

## The instant and the label An aware datetime carries two things: a set of wall-clock fields (year, month, day, hour, minute, second, microsecond) and a `tzinfo`. Together they identify an instant. Change one half and you must decide which of the two you meant to preserve. * **`astimezone(tz)` preserves the instant.** It asks the current tzinfo for the offset, converts to UTC internally, asks the target tzinfo for the offset at that moment, and rewrites the wall-clock fields accordingly. The absolute moment is untouched, so `dt.astimezone(tz) == dt` is true. * **`replace(tzinfo=tz)` preserves the fields.** `replace` is the generic "make a copy with these attributes changed" method on `datetime`, and `tzinfo` is just another attribute to it. Nothing is converted. The digits you see stay, the zone changes underneath them, and the instant therefore moves. ```python from datetime import datetime, timezone from zoneinfo import ZoneInfo stored = datetime(2026, 7, 15, 12, 0, tzinfo=timezone.utc) stored.astimezone(ZoneInfo("Asia/Tokyo")) # 21:00+09:00, same instant stored.replace(tzinfo=ZoneInfo("Asia/Tokyo")) # 12:00+09:00, nine hours earlier ``` Both lines run. Both produce a perfectly valid aware datetime. Only one of them means what the author almost certainly intended, and the difference will surface later as records that are consistently some whole number of hours out. ## When `replace(tzinfo=...)` is the right call There is exactly one common case: you have a value with no zone at all — parsed from a file, a form field, an instrument's export — and you know from context which zone it was recorded in. Attaching the zone is a statement of fact about the data, not a conversion, so `replace(tzinfo=ZoneInfo(key))` is correct and `astimezone` would be wrong (it would assume the value was already in the machine's local zone before converting). Attach first, then convert. The corollary: if the value already has a `tzinfo`, `replace(tzinfo=...)` is almost always a mistake. Reviewers should treat it as a smell on an aware value and ask what the author meant. ## `astimezone` with no argument `dt.astimezone()` with no target converts to the **system local zone**, determined from the platform's configuration. That is convenient in a script and a liability in a service: the result depends on the machine, the container image, and the process environment rather than on anything in your code. In server code, pass the target zone explicitly — `astimezone(datetime.timezone.utc)` or `astimezone(ZoneInfo(key))` — so behaviour is identical everywhere the code runs. One related trap: calling `astimezone` on a *naive* datetime does not raise. Since Python 3.6, a naive value is assumed to be in the system local zone and converted from there. That silently pulls the machine's configuration into your data path, which is another reason to attach the intended zone deliberately rather than letting the platform guess. ## Why the round trip matters more than the display The conversion contract is what makes the store-UTC, render-local pattern safe. Because `astimezone` is instant-preserving, `utc_value.astimezone(zone).astimezone(datetime.timezone.utc)` returns the value you started with, and equality and ordering between two aware datetimes are computed on the underlying instants regardless of which zones they carry. So two aware datetimes in different zones compare correctly, sort correctly, and subtract correctly — provided you never relabelled one of them with `replace`. A relabel destroys that property quietly. The value still sorts, still subtracts, still formats; it is simply the wrong moment. There is no exception, no warning, and no type-checker complaint, because both operations return `datetime`. ## Relabelling to a fixed offset A second-order version of the same mistake: taking an aware datetime and doing `replace(tzinfo=datetime.timezone(timedelta(hours=9)))` to "pin" it. Even if the offset happens to be right today, the value now carries a frozen number instead of a rule set, so any later conversion or any neighbouring date in another part of the year is computed against the wrong rules. If you want a fixed offset, convert into it with `astimezone` rather than stamping it on. ## Checklist for review * Value is aware and you want it displayed elsewhere → `astimezone(target)`. * Value is naive and you know its zone → `replace(tzinfo=ZoneInfo(key))`, then convert. * `astimezone()` with no argument in a service → make the target explicit. * `replace(tzinfo=...)` on something already aware → justify it or fix it.