Python Reference ยท Standard Library: Math, Data and Text
The zoneinfo module
Reference for Python's zoneinfo module: create ZoneInfo objects for IANA zones, convert between time zones, handle daylight saving time and missing data.
The zoneinfo module (new in Python 3.9) lets datetime objects use the IANA time zone database, the same data your operating system and most websites use. A ZoneInfo("Europe/Paris") knows the zone's history, including daylight saving time (DST) rules, so the same zone gives different UTC offsets in summer and winter.
Use it for real regions. For a fixed offset such as UTC+5, datetime.timezone is enough. The standard workflow is: store and compute in UTC, then convert to a user's zone with astimezone() when you display a value.
from datetime import datetime import tzdata # Pyodide: makes the time zone data available from zoneinfo import ZoneInfo dt = datetime(2030, 7, 1, 12, 0, tzinfo=ZoneInfo("Europe/Paris"))
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Syntax
ZoneInfo(key) ZoneInfo.no_cache(key) ZoneInfo.from_file(fobj, key=None) zoneinfo.available_timezones() zoneinfo.reset_tzpath(to=None)
| Name | Description |
|---|---|
key |
An IANA name such as "Europe/Paris" or "UTC". Case-sensitive. |
ZoneInfo.key |
The key the object was created with. |
ZoneInfo.no_cache(key) |
Builds a new object instead of using the cached one. |
available_timezones() |
Set of all zone keys found on this system. Slow, because it scans the files. |
reset_tzpath(to) |
Changes the search path for zone data files. |
Raises: ZoneInfoNotFoundError (a subclass of KeyError) for an unknown key. ValueError for malformed keys, such as an absolute path.
Usage notes
- Pass
tzinfo=ZoneInfo(...)to the constructor orreplace(). Do not use the oldpytzstylelocalize(); withzoneinfoattaching the zone directly is correct. - Arithmetic inside a zone is wall-clock arithmetic. Adding
timedelta(hours=1)to an aware datetime does not account for a DST jump. Convert to UTC for real elapsed time, as shown above. - Gaps and folds. A time that never happens (spring forward) is still accepted. A time that happens twice (fall back) is resolved with the
foldattribute: 0 is the first occurrence, 1 the second. - Time zone data comes from the system. Windows and some minimal containers have no IANA database, so install the
tzdatapackage from PyPI (pip install tzdata);zoneinfouses it automatically as a fallback. If data is missing you getZoneInfoNotFoundError. - In the browser runner there is no system zone database, so the examples above run
import tzdatafirst, which loads the PyPI data package. Your own scripts do not need that line when the system has zone data. - Objects are cached, so
ZoneInfo("UTC") is ZoneInfo("UTC")isTrue, and comparing zones is cheap. - Pickling a
ZoneInfostores only its key. - Zone names change. Governments alter DST rules; keep
tzdataupdated for future dates.
Related
datetime,time,calendar- Lessons: Dates and times