tzdata

2025.3 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install 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

uv add tzdata

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - 20.6M

3.10 slim (glibc) - - - 21M

3.11 alpine (musl) - - - 22.4M

3.11 slim (glibc) - - - 23M

3.12 alpine (musl) - - - 14.3M

3.12 slim (glibc) - - - 15M

3.13 alpine (musl) - - - 14.0M

3.13 slim (glibc) - - - 14M

3.9 alpine (musl) - - - 20.1M

3.9 slim (glibc) - - - 21M

Imports

ZoneInfo
wrong
```
import tzdata  # tzdata has no public end-user API; do not call or instantiate it directly
```
correct
```
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 verified last tested: 2026-04-23

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