tzdata

library2026.3pypypi✓ verified 26d ago

tzdata is a data-only Python package containing zic-compiled binaries for the IANA time zone database, maintained by the CPython core developers. It serves as a cross-platform fallback for the standard library's zoneinfo module (Python 3.9+, PEP 615) on systems that lack system-level zone data — most critically Windows. The current version is 2025.3 (wrapping upstream IANA tzdata 2025c). Releases track IANA upstream closely, typically producing between 3 and 10+ releases per year in response to real-world timezone rule changes.

data serialization

pip install tzdata

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · TZDATA

tzdata

datapythonv2026.3

Install

1.8s avg

Import

—

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2026.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 20.6MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.000s · 21MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ZoneInfo

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

✗ import tzdata # tzdata has no public end-user API; do not call or instantiate it directly

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).

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())}')

Debug

Known issues

breakingOn 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.

affects: all

gotchaOn 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.

affects: all

gotchaPinning 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.

affects: all

breakingZoneInfo 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.

affects: all

gotchaimport 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.

affects: all

gotchazoneinfo.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.

affects: all

deprecatedThe 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.

affects: <3.11

Upgrade

Version history

2026.3latest on PyPI · released Jul 10, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

62 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/python/tzdata ↗

packagehttps://pypi.org/project/tzdata/ ↗

docshttps://tzdata.python.org ↗