Python's datetime objects come in two flavors: naive (no tzinfo attribute) and aware (with tzinfo set). datetime.now() returns a naive datetime by default, which silently picks up the server's local time zone when serialized or compared. A codebase developed locally in JST and deployed on UTC servers can easily produce nine-hour offset bugs that no test catches because both sides agreed to the wrong assumption.
The professional rule is to convert input timestamps to aware as early as possible, perform all internal computation in aware, and serialize back to strings only at the boundaries. Mixing naive and aware datetimes in arithmetic raises TypeError, so adding type aliases that distinguish AwareDatetime from datetime in mypy or pyright provides a strong static safeguard.
PEP 615 introduced the zoneinfo module in Python 3.9, providing direct access to the IANA time zone database without third-party dependencies. zoneinfo.ZoneInfo("Asia/Tokyo") returns a tzinfo instance you can pass directly to datetime, eliminating an entire category of pytz-specific quirks. Removing a third-party package also simplifies dependency management and supply chain auditing.
By default, zoneinfo reads tzdata from the operating system. Linux and macOS ship with /usr/share/zoneinfo populated, but Windows lacks IANA data out of the box. The standard remedy is pip install tzdata, which provides a Python package that zoneinfo will fall back to. Alpine-based Docker images, often chosen for their small size, also lack tzdata by default and must be configured explicitly.
pytz has been the de facto choice for IANA time zones since 2003. It works on every Python version still in use, but it has an unusual API. You cannot pass a pytz timezone directly into the datetime constructor; doing so initializes the datetime with a historical Local Mean Time (LMT) offset that is several minutes off from the modern standard. For Tokyo, this LMT bug yields a 9 hour 19 minute offset instead of the expected 9 hours.
The correct pytz pattern is to use tz.localize(naive_dt) for naive datetimes or dt.astimezone(tz) for already-aware ones. When migrating to zoneinfo, the tz.normalize() calls scattered through pytz codebases can be removed entirely, since zoneinfo's arithmetic produces the correct result without manual normalization.
Python 3.6 added the fold attribute to datetime to resolve a long-standing problem: when daylight saving time ends, the same wall-clock time occurs twice. On November 1, 2026 at 1:30 AM in U.S. Eastern Time, the moment is ambiguous. fold=0 selects the first occurrence (EDT, UTC-4) and fold=1 selects the second (EST, UTC-5). Without this distinction, programs cannot represent both moments unambiguously.
The opposite case, when DST starts and a wall-clock time skips forward, leaves a gap that does not exist on the clock. zoneinfo treats this skipped time as if it were the prior moment, but applications doing alarm scheduling or job timing must handle both situations explicitly. Boundary tests should include both the spring-forward gap and the fall-back overlap.
The IANA time zone database receives 5 to 10 updates per year, reflecting policy changes such as DST abolition or standard time adjustments. As of 2026, several countries continue to debate their DST policies, meaning a system with stale tzdata may compute incorrect future times. Container deployments are particularly susceptible, because the base image's tzdata version is fixed at build time and only refreshed when the image is rebuilt.
On managed runtimes such as AWS Lambda or Cloud Run, you cannot directly verify the bundled tzdata version. For mission-critical workloads computing future timestamps, the safest approach is to install the tzdata package via pip and configure ZoneInfo to prefer it via the TZPATH environment variable. This puts the time zone data version under explicit control rather than hidden inside the runtime.
For new projects on Python 3.9 or later, zoneinfo is the right default. In existing codebases mixing pytz and zoneinfo, the two can coexist behind tzinfo without immediate refactoring. Migrate one boundary at a time, starting from API ingress and egress, and the changes propagate gradually through the system without big-bang rewrites.
Equally important is the policy of keeping internal state in UTC. Performing arithmetic in Asia/Tokyo or America/Los_Angeles invites DST-related surprises. Convert at the input boundary, compute in UTC, and convert back only when displaying to a user or persisting in a column whose semantics require local time. PostgreSQL's TIMESTAMP WITH TIME ZONE always stores UTC internally, making it the natural counterpart to this approach.
Was this article helpful?
Each major programming language has evolved its date and time API in different directions. This article compares JavaScript's Temporal, Python's datetime + zoneinfo, and Java's java.time, surveys common pitfalls, and offers selection guidance for new and existing projects.
The java.time API introduced in Java 8 offers five primary classes for representing dates and times. Knowing when to use Instant, OffsetDateTime, ZonedDateTime, LocalDateTime, or LocalDate is the key to avoiding time zone bugs. This article walks through each class with practical guidance for Spring Boot and JPA projects.
MySQL timezone bugs almost always trace back to a misunderstanding of three layers: server defaults, session settings, and column types. This article explains why TIMESTAMP and DATETIME behave differently, how the time_zone variable interacts with connections, and how to configure JDBC drivers correctly.