Install & Compatibility
Where this runs
tested against v2026.3.1.20260727 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
timezone
✓ from pytz-stubs import timezone
✗ from pytz import timezone
This quickstart demonstrates basic usage of `pytz` for creating and converting timezone-aware `datetime` objects. Installing `types-pytz` enables static type checkers to verify the types in such operations, enhancing code reliability.
from datetime import datetime
from pytz import timezone, utc
# Create a naive datetime object
naive_dt = datetime(2024, 7, 21, 10, 30, 0)
print(f"Naive Datetime: {naive_dt}")
# Get a timezone object
eastern = timezone('America/New_York')
# Localize the naive datetime (make it timezone-aware)
aware_dt_eastern = eastern.localize(naive_dt)
print(f"Aware Datetime (Eastern): {aware_dt_eastern}")
# Convert to UTC
aware_dt_utc = aware_dt_eastern.astimezone(utc)
print(f"Aware Datetime (UTC): {aware_dt_utc}")
# Get current time in a specific timezone
current_paris_time = datetime.now(timezone('Europe/Paris'))
print(f"Current Paris Time: {current_paris_time}")
def get_current_utc() -> datetime:
"""Returns the current UTC time with timezone awareness."""
return datetime.now(utc)
# Demonstrate type checking with a function call
current_utc = get_current_utc()
print(f"Current UTC (from typed function): {current_utc}")
Debug
Known issues
gotchaThe `types-pytz` package only provides typing stubs and does NOT install the actual `pytz` runtime library. You must explicitly install `pytz` (e.g., `pip install pytz`) for your code to run, in addition to `types-pytz` for type checking.fixEnsure both `pytz` and `types-pytz` are installed: `pip install pytz types-pytz`.
affects: All versions
gotchaFor Python 3.9 and later, the built-in `zoneinfo` module (part of the standard library) is generally preferred over `pytz` for timezone handling. `zoneinfo` offers better integration with `datetime`, more intuitive API, and avoids some of `pytz`'s historical complexities and potential issues (e.g., the 2038 bug).fixConsider migrating to `zoneinfo`. For a smoother transition, the `pytz-deprecation-shim` library can help. Example `zoneinfo` usage: `from datetime import datetime; from zoneinfo import ZoneInfo; dt = datetime.now(ZoneInfo('America/New_York'))`. affects: Python 3.9 and later
gotchaWhen localizing naive `datetime` objects with `pytz`, it's crucial to use the `.localize()` method of a `pytz` timezone object (e.g., `tz.localize(naive_dt)`). Directly assigning a `pytz` timezone object to a `datetime`'s `tzinfo` attribute (e.g., `naive_dt.replace(tzinfo=tz)`) is often incorrect and can lead to `AmbiguousTimeError`, `NonExistentTimeError`, or subtle shifts to incorrect historical offsets like Local Mean Time (LMT).fixAlways use `pytz.timezone('Continent/City').localize(naive_datetime)` or create timezone-aware datetimes directly with `datetime.now(tz=pytz.utc)` or `datetime(..., tzinfo=pytz.utc)` for UTC. For converting existing aware datetimes, use `.astimezone()`. affects: All versions
gotchaThe `types-pytz` package is developed and released to provide accurate type annotations for specific versions of the `pytz` library. Mismatches between the installed `types-pytz` version and the `pytz` runtime version can lead to incorrect type-checking results (e.g., missing attributes or wrong argument types).fixConsult the `types-pytz` PyPI page or typeshed `README` for the target `pytz` version it supports. Ensure your `pytz` installation is compatible, upgrading or downgrading if necessary.
affects: All versions
Upgrade
Version history
2026.3.1.20260727latest on PyPI · released Jul 27, 2026
Audit
Dependencies
pytzrequiredThis package provides type stubs for 'pytz'. The 'pytz' library itself must be installed and present at runtime for your code to function. 'types-pytz' only provides the type definitions.