pytz

pytz brings the IANA (formerly Olson) time zone database into Python, giving applications accurate, cross-platform timezone calculations that stay correct across daylight-saving transitions and historical offset changes. It exposes every zone in the tz database as a ready-to-use tzinfo object, along with helpers for localizing naive datetimes, normalizing arithmetic results, and enumerating common or country-specific zones.

For well over a decade pytz was the de-facto timezone layer for the Python ecosystem, underpinning Django, pandas, and countless web and data applications. Its data is regenerated several times a year to track upstream IANA releases, so deployments get up-to-date rules without waiting on the host operating system.

What You Get

• The full IANA/Olson tz database bundled as Python tzinfo objects, refreshed several times a year
• timezone() lookup plus localize() and normalize() helpers for DST-correct datetime handling
• Curated lists such as common_timezones, all_timezones, and country_timezones for building pickers and validators

Common Use Cases

• Storing and converting timestamps across regions in web and API backends
• Rendering event times in a user’s local zone while keeping UTC as the canonical store
• Validating and populating timezone selection fields from a maintained zone list

Under The Hood

Architecture - pytz separates generated data from runtime logic: the top-level repo generates code via gen_tzinfo.py from the upstream IANA tarballs, while the shipped package in src/pytz exposes a thin API surface (init.py) over compiled zone definitions. timezone() resolves a zone name to a tzinfo built by tzfile.build_tzinfo() from binary zoneinfo resources, and LazyDict/LazyList in lazy.py defer loading of the large zone lists until first access to keep import cheap.

Tech Stack - The distributable is pure Python (setup.py, packaging pytz plus its zoneinfo data files) targeting everything from Python 2.4 through 3.13, with zero runtime dependencies. The surrounding repository uses C, Makefiles, and awk to regenerate the tz database from IANA sources, but none of that toolchain is required by consumers who only install the Python package.

Code Quality - The library carries a dedicated tests directory (test_tzinfo.py, test_lazy.py, test_docs.py) plus doctests embedded throughout init.py, and defines a clear exception hierarchy (AmbiguousTimeError, NonExistentTimeError, UnknownTimeZoneError) for edge cases. The code is conservative and heavily commented, retaining Python 2/3 compatibility shims that reflect its long maintenance history rather than modern idioms.

API Design - The public API is small and well documented: pytz.timezone(name) returns a tzinfo, and the localize()/normalize() pattern is the established idiom for DST-correct handling. The main ergonomic caveat is that datetime’s own tzinfo constructor argument must not be used with pytz zones — you must call localize() instead — a well-known footgun documented prominently in the README.