tzdata

Warnings

• breaking On Windows and minimal Linux containers (e.g. python:3.x-slim, Alpine without tzdata OS package), ZoneInfo raises ZoneInfoNotFoundError for every key if tzdata is not installed. The stdlib zoneinfo module itself does not bundle any data.
  Fix: Add tzdata as an explicit dependency in requirements.txt / pyproject.toml. Do not rely on it being present transitively.
• gotcha On Linux/macOS, zoneinfo silently prefers system-level /usr/share/zoneinfo over the installed tzdata package. A stale or outdated system tzdata can shadow a freshly pip-installed tzdata, causing subtle DST/offset divergence between platforms.
  Fix: Set PYTHONTZPATH='' to force exclusive use of the pip-installed tzdata, or ensure the OS tzdata package is also kept current. For reproducible cross-platform builds, set PYTHONTZPATH='' in CI.
• gotcha Pinning tzdata to a specific version (e.g. tzdata==2024.1) means your application will use stale timezone rules. IANA releases corrections multiple times per year, sometimes affecting future timestamps with very little notice.
  Fix: Use a minimum-version pin (tzdata>=2025.1) rather than an exact pin, and update regularly. Consider renovate/dependabot for automated updates.
• breaking ZoneInfo objects created via ZoneInfo.from_file() (no key set) cannot be pickled. Pickling ZoneInfo objects that were sourced from tzdata requires the same tzdata version to be present on the deserializing host; unpickling against a different version gives no error but may silently produce incorrect offsets.
  Fix: Avoid pickling ZoneInfo objects across environments with different tzdata versions. Serialize the zone key string instead and reconstruct with ZoneInfo(key) on the receiving end.
• gotcha import tzdata itself does nothing useful for end users — the package exposes no callable API. Common mistake is calling tzdata() or tzdata.create() as if it were a factory, which raises AttributeError.
  Fix: Use from zoneinfo import ZoneInfo for all timezone lookups. Only access tzdata.IANA_VERSION for version introspection, or use importlib.resources on tzdata.zoneinfo.* sub-packages when writing a timezone library.
• gotcha zoneinfo.available_timezones() scans all sources on TZPATH plus tzdata; on systems with both system data and tzdata installed, the returned set reflects the union and count may vary across platforms, making set equality assertions in tests fragile.
  Fix: Use assertIn / subset checks rather than set equality when testing available timezones. Force a deterministic source in tests by setting PYTHONTZPATH='' (to use only tzdata) or by calling zoneinfo.reset_tzpath([]) at test setup.
• deprecated The importlib.resources.open_binary() API used in the official tzdata docs for library authors is deprecated in Python 3.11 in favour of importlib.resources.files().
  Fix: On Python 3.11+, use: importlib.resources.files('tzdata.zoneinfo.America').joinpath('New_York').open('rb'). For compatibility across versions, use the importlib_resources backport.

Install

• pip install tzdata pip
• uv add tzdata uv

Imports

• ZoneInfo

  from zoneinfo import ZoneInfo  # stdlib (Python 3.9+); tzdata is consumed automatically as a fallback

  tzdata is a data package — end users interact with it exclusively through zoneinfo.ZoneInfo or dateutil.tz. Importing tzdata directly exposes only IANA_VERSION and internal zoneinfo binary resources.
• IANA_VERSION

  import tzdata; print(tzdata.IANA_VERSION)

  The only stable public symbol on the tzdata package itself. Useful for diagnostics and version assertions.
• open_binary (library authors only)

  from importlib import resources
  with resources.open_binary('tzdata.zoneinfo.America', 'New_York') as f:
      data = f.read()

  For timezone library authors needing raw TZif bytes. Each subfolder of tzdata.zoneinfo is a separate importlib package (e.g. tzdata.zoneinfo.America.Indiana for multi-level zones).

Quickstart

Basic cross-platform timezone-aware datetime using zoneinfo backed by tzdata. No auth or env vars required — tzdata is pure data.

# tzdata acts as a silent fallback — no explicit import required for end users.
# Install tzdata, then use zoneinfo normally:
from datetime import datetime
from zoneinfo import ZoneInfo

# Works on all platforms (including Windows) once tzdata is installed
dt_ny = datetime.now(ZoneInfo('America/New_York'))
dt_utc = datetime.now(ZoneInfo('UTC'))
print(f'New York : {dt_ny}')
print(f'UTC      : {dt_utc}')

# Check which IANA version is bundled
import tzdata
print(f'IANA tzdata version: {tzdata.IANA_VERSION}')

# Verify tzdata is active as the data source (useful on Windows / minimal containers)
from zoneinfo import available_timezones
print(f'Available zones: {len(available_timezones())}')