{"id":3845,"library":"types-tzlocal","title":"Typing Stubs for tzlocal","description":"types-tzlocal provides static type annotations (stubs) for the `tzlocal` library, which is used to obtain the local timezone as a `tzinfo` object. The current version, 5.1.0.1, specifically targets `tzlocal` versions up to 5.1. Note that as of `tzlocal` version 5.2, the core library includes its own type annotations, making `types-tzlocal` redundant for newer versions of `tzlocal`. It is maintained as part of the `typeshed` project and receives updates aligned with `tzlocal` releases.","status":"active","version":"5.1.0.1","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed/tree/main/stubs/tzlocal","tags":["typing","stubs","timezone","typeshed","tzinfo"],"install":[{"cmd":"pip install types-tzlocal","lang":"bash","label":"Install types-tzlocal"}],"dependencies":[{"reason":"This package provides type stubs for the 'tzlocal' runtime library. 'tzlocal' itself requires 'tzdata'.","package":"tzlocal","optional":false}],"imports":[{"symbol":"get_localzone","correct":"from tzlocal import get_localzone"},{"note":"Only use if the timezone name is strictly required; get_localzone() is generally preferred.","symbol":"get_localzone_name","correct":"from tzlocal import get_localzone_name"}],"quickstart":{"code":"from datetime import datetime\nfrom tzlocal import get_localzone\n\n# Get the local timezone tzinfo object\nlocal_tz = get_localzone()\nprint(f\"Local timezone: {local_tz}\")\n\n# Create a timezone-aware datetime object\nnow_naive = datetime.now()\nnow_aware = local_tz.localize(now_naive)\nprint(f\"Timezone-aware datetime: {now_aware}\")\n\n# Get just the timezone name (may fail on some Unix systems)\ntry:\n    local_tz_name = get_localzone_name()\n    print(f\"Local timezone name: {local_tz_name}\")\nexcept Exception as e:\n    print(f\"Could not get local timezone name: {e}\")","lang":"python","description":"Demonstrates how to retrieve the local timezone `tzinfo` object and create a timezone-aware `datetime` object using `tzlocal`. It also shows how to get the timezone name, with a note about potential failures on some systems."},"warnings":[{"fix":"Either pin 'tzlocal<5' if `pytz` compatibility is essential, or update your code to work with `zoneinfo.ZoneInfo` objects (standard in Python 3.9+).","message":"With tzlocal version 5.0, the `pytz_deprecation_shim` was removed. This means `tzlocal.get_localzone()` now exclusively returns `zoneinfo` objects, similar to version 3.0. If your application relies on `pytz` objects, you must remain on `tzlocal` version 4.x or adapt your code to `zoneinfo`'s API.","severity":"breaking","affected_versions":"tzlocal >= 5.0"},{"fix":"Run `pip uninstall types-tzlocal` if your `tzlocal` version is 5.2 or higher.","message":"Since `tzlocal` version 5.2, the `tzlocal` library itself bundles its type annotations (stubs). If you are using `tzlocal` 5.2 or newer, `types-tzlocal` becomes redundant and should be uninstalled to avoid potential conflicts or unnecessary package overhead.","severity":"gotcha","affected_versions":"tzlocal >= 5.2"},{"fix":"Ensure your operating system's timezone configuration is correctly set up. If only the `tzinfo` object is needed, prefer `get_localzone()` over `get_localzone_name()`.","message":"On some Unix-like systems, if the timezone name is not properly configured (e.g., in `/etc/timezone` or via symlinks), `tzlocal.get_localzone_name()` might raise an error, while `tzlocal.get_localzone()` would still successfully return a `tzinfo` object. Unconfigured systems might default to UTC.","severity":"gotcha","affected_versions":"All versions of tzlocal"},{"fix":"Migrate to using `zoneinfo.ZoneInfo` objects (native in Python 3.9+) or other modern timezone handling, or explicitly manage `pytz` directly if specific `pytz` features are required.","message":"The `pytz_deprecation_shim` was introduced in `tzlocal` 4.0 to restore partial `pytz` compatibility after `tzlocal` 3.0 switched to `zoneinfo` objects. This shim was then removed in `tzlocal` 5.0. Relying on it for `pytz` compatibility in `tzlocal` 4.x is a temporary measure and should be migrated away from.","severity":"deprecated","affected_versions":"tzlocal 4.x (usage of shim)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}