{"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":"python","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":[{"wrong":"from tzlocal-stubs import get_localzone","symbol":"get_localzone","correct":"from tzlocal import get_localzone"}],"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,"search_vec":"'5.1':39 '5.1.0.1':32 '5.2':46 'align':77 'annot':11,54 'core':48 'current':30 'includ':50 'librari':16,49 'local':23 'maintain':67 'make':55 'newer':61 'note':40 'object':28 'obtain':21 'part':69 'project':73 'provid':8 'receiv':75 'redund':59 'releas':80 'specif':33 'static':9 'stub':2,12,82 'target':34 'timezon':24,83 'type':1,6,10,53,57,81 'types-tzloc':5,56 'typesh':72,84 'tzinfo':27,85 'tzlocal':4,7,15,35,44,58,64,79 'updat':76 'use':19 'version':31,36,45,62","created_at":"2026-04-11T17:47:08.736155+00:00","updated_at":"2026-04-11T17:47:08.736155+00:00","problems":{"verify_error":"Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\nModuleNotFoundError: No module named 'tzlocal'"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"5.1.0.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/tzlocal.md","pypi":"https://pypi.org/project/types-tzlocal/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-08-29","next_check":"2026-07-10","install_tag":null}}