{"id":721,"library":"types-pytz","title":"Typing Stubs for pytz","description":"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.","status":"active","version":"2026.1.1.20260304","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","timezone","pytz","type-checking"],"install":[{"cmd":"pip install types-pytz","lang":"bash","label":"Install types-pytz"}],"dependencies":[{"reason":"This 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.","package":"pytz","optional":false}],"imports":[{"symbol":"timezone","correct":"from pytz import timezone"},{"symbol":"utc","correct":"from pytz import utc"},{"note":"Type stubs define types for the original library; import types directly from `pytz` for type hints, not from `types-pytz`.","wrong":"from types_pytz.tzinfo import DstTzInfo","symbol":"DstTzInfo","correct":"from pytz.tzinfo import DstTzInfo"}],"quickstart":{"code":"from datetime import datetime\nfrom pytz import timezone, utc\n\n# Create a naive datetime object\nnaive_dt = datetime(2024, 7, 21, 10, 30, 0)\nprint(f\"Naive Datetime: {naive_dt}\")\n\n# Get a timezone object\neastern = timezone('America/New_York')\n\n# Localize the naive datetime (make it timezone-aware)\naware_dt_eastern = eastern.localize(naive_dt)\nprint(f\"Aware Datetime (Eastern): {aware_dt_eastern}\")\n\n# Convert to UTC\naware_dt_utc = aware_dt_eastern.astimezone(utc)\nprint(f\"Aware Datetime (UTC): {aware_dt_utc}\")\n\n# Get current time in a specific timezone\ncurrent_paris_time = datetime.now(timezone('Europe/Paris'))\nprint(f\"Current Paris Time: {current_paris_time}\")\n\ndef get_current_utc() -> datetime:\n    \"\"\"Returns the current UTC time with timezone awareness.\"\"\"\n    return datetime.now(utc)\n\n# Demonstrate type checking with a function call\ncurrent_utc = get_current_utc()\nprint(f\"Current UTC (from typed function): {current_utc}\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure both `pytz` and `types-pytz` are installed: `pip install pytz types-pytz`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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'))`.","message":"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).","severity":"gotcha","affected_versions":"Python 3.9 and later"},{"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()`.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:16:08.455Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install types-pytz","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.","error":"error: Library \"pytz\" has no or incomplete types"},{"fix":"pip install types-pytz","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.","error":"error: Module \"pytz\" has no attribute \"utc\""},{"fix":"Ensure you pass a `pytz` timezone object (e.g., created via `pytz.timezone(\"America/New_York\")` or `pytz.utc`) to `pytz.localize`.","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.","error":"error: Argument \"tzinfo\" to \"localize\" of \"pytz\" has incompatible type \"datetime.tzinfo\"; expected \"BaseTzInfo\""}],"ecosystem":"pypi","meta_description":null,"install_score":0,"install_tag":"stale","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"2026.2.0.20260506","install_checks":{"last_tested":"2026-05-12","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.8M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"19.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":null,"mem_mb":null,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":null,"mem_mb":null,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":"17.3M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.7,"import_time_s":null,"mem_mb":null,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":1,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":null,"mem_mb":null,"disk_size":null}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}