{"id":287,"library":"tzdata","title":"tzdata","description":"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.","status":"active","version":"2025.3","language":"python","source_language":"en","source_url":"https://github.com/python/tzdata","tags":["timezone","iana","zoneinfo","datetime","stdlib-companion","windows","data-package","pep615"],"install":[{"cmd":"pip install tzdata","lang":"bash","label":"pip"},{"cmd":"uv add tzdata","lang":"bash","label":"uv"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import tzdata  # tzdata has no public end-user API; do not call or instantiate it directly","symbol":"ZoneInfo","correct":"from zoneinfo import ZoneInfo  # stdlib (Python 3.9+); tzdata is consumed automatically as a fallback"},{"note":"The only stable public symbol on the tzdata package itself. Useful for diagnostics and version assertions.","symbol":"IANA_VERSION","correct":"import tzdata; print(tzdata.IANA_VERSION)"},{"note":"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).","symbol":"open_binary (library authors only)","correct":"from importlib import resources\nwith resources.open_binary('tzdata.zoneinfo.America', 'New_York') as f:\n    data = f.read()"}],"quickstart":{"code":"# tzdata acts as a silent fallback — no explicit import required for end users.\n# Install tzdata, then use zoneinfo normally:\nfrom datetime import datetime\nfrom zoneinfo import ZoneInfo\n\n# Works on all platforms (including Windows) once tzdata is installed\ndt_ny = datetime.now(ZoneInfo('America/New_York'))\ndt_utc = datetime.now(ZoneInfo('UTC'))\nprint(f'New York : {dt_ny}')\nprint(f'UTC      : {dt_utc}')\n\n# Check which IANA version is bundled\nimport tzdata\nprint(f'IANA tzdata version: {tzdata.IANA_VERSION}')\n\n# Verify tzdata is active as the data source (useful on Windows / minimal containers)\nfrom zoneinfo import available_timezones\nprint(f'Available zones: {len(available_timezones())}')","lang":"python","description":"Basic cross-platform timezone-aware datetime using zoneinfo backed by tzdata. No auth or env vars required — tzdata is pure data."},"warnings":[{"fix":"Add tzdata as an explicit dependency in requirements.txt / pyproject.toml. Do not rely on it being present transitively.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"fix":"Use a minimum-version pin (tzdata>=2025.1) rather than an exact pin, and update regularly. Consider renovate/dependabot for automated updates.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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().","severity":"deprecated","affected_versions":"<3.11"}],"env_vars":null,"last_verified":"2026-05-12T12:51:36.790Z","next_check":"2026-06-26T00:00:00.000Z","problems":[],"ecosystem":"pypi","meta_description":null,"install_score":80,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"20.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"21M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"22.4M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"23M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"14.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"15M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"14.0M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"14M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"20.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"21M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}