Skip to content
Tutorials Center
My learning

Topics

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.

Python
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

Python Attaching and converting zones

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.

Python Daylight saving gaps and errors

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

Python
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 or replace(). Do not use the old pytz style localize(); with zoneinfo attaching 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 fold attribute: 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 tzdata package from PyPI (pip install tzdata); zoneinfo uses it automatically as a fallback. If data is missing you get ZoneInfoNotFoundError.
  • In the browser runner there is no system zone database, so the examples above run import tzdata first, 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") is True, and comparing zones is cheap.
  • Pickling a ZoneInfo stores only its key.
  • Zone names change. Governments alter DST rules; keep tzdata updated for future dates.