Typing Stubs for pytz

2026.1.1.20260304 verified Tue May 12 auth: no python install: stale quickstart: stale

types-pytz provides static type checking annotations (typing stubs) for the `pytz` library. It enables type checkers like MyPy and Pyright to analyze code that uses `pytz` for timezone operations, helping to catch type-related errors before runtime. As of its latest version `2026.1.1.20260304`, it aims to provide accurate annotations for `pytz==2026.1.post1` and is part of the actively maintained Typeshed project, which releases updates frequently.

pip install types-pytz

Common errors

error error: Library "pytz" has no or incomplete types ↓

cause MyPy cannot find type annotations for the `pytz` library, indicating that `types-pytz` is not installed or not correctly configured for MyPy to find.

fix

pip install types-pytz

error error: Module "pytz" has no attribute "utc" ↓

cause MyPy cannot resolve the `utc` attribute on the `pytz` module, typically because the `types-pytz` stub package is either missing or not correctly processed, preventing MyPy from seeing the `pytz` interface.

fix

pip install types-pytz

error error: Argument "tzinfo" to "localize" of "pytz" has incompatible type "datetime.tzinfo"; expected "BaseTzInfo" ↓

cause You are attempting to pass a standard `datetime.tzinfo` object to `pytz.localize`, but `pytz` expects its own specific `BaseTzInfo` instances for proper timezone handling. `types-pytz` correctly highlights this incompatibility.

fix

Ensure you pass a pytz timezone object (e.g., created via pytz.timezone("America/New_York") or pytz.utc) to pytz.localize.

Warnings

gotcha The `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. ↓

fix Ensure both `pytz` and `types-pytz` are installed: `pip install pytz types-pytz`.

gotcha For 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). ↓

fix Consider 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'))`.

gotcha When 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). ↓

fix Always 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()`.

gotcha The `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). ↓

fix Consult 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.

Install compatibility stale last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - - 17.8M

3.10 alpine (musl) - - - -

3.10 slim (glibc) wheel 1.4s - 18M

3.10 slim (glibc) - - - -

3.11 alpine (musl) wheel - - 19.6M

3.11 alpine (musl) - - - -

3.11 slim (glibc) wheel 1.6s - 20M

3.11 slim (glibc) - - - -

3.12 alpine (musl) wheel - - 11.5M

3.12 alpine (musl) - - - -

3.12 slim (glibc) wheel 1.4s - 12M

3.12 slim (glibc) - - - -

3.13 alpine (musl) wheel - - 11.3M

3.13 alpine (musl) - - - -

3.13 slim (glibc) wheel 1.4s - 12M

3.13 slim (glibc) - - - -

3.9 alpine (musl) wheel - - 17.3M

3.9 alpine (musl) - - - -

3.9 slim (glibc) wheel 1.7s - 18M

3.9 slim (glibc) - - - -

Imports

timezone
```
from pytz import timezone
```
utc
```
from pytz import utc
```
DstTzInfo
wrong
```
from types_pytz.tzinfo import DstTzInfo
```
correct
```
from pytz.tzinfo import DstTzInfo
```
Type stubs define types for the original library; import types directly from `pytz` for type hints, not from `types-pytz`.

Quickstart stale last tested: 2026-04-24

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}")