tzlocal

tzlocal solves a small but consistently annoying problem: Python’s standard library has no reliable, cross-platform way to ask “what timezone is this machine set to?” tzlocal inspects /etc/timezone, /etc/localtime, environment variables, and systemd/dbus on Linux, NSTimeZone-equivalent system calls on macOS, and the Windows registry (via a maintained IANA-to-Windows timezone name mapping) to return a proper zoneinfo/pytz-compatible tzinfo object.

It’s a small, focused dependency pulled in transitively by much larger packages (APScheduler, various datetime and scheduling libraries) whenever they need to default to “the user’s local timezone” without asking the user to specify it explicitly.

What You Get

• get_localzone() — a single function that returns the system’s local timezone as a zoneinfo.ZoneInfo (or pytz timezone if configured) object
• Platform detection logic for Linux/Unix (/etc/timezone, /etc/localtime, systemd/dbus), macOS, and Windows
• A maintained IANA <-> Windows timezone name mapping (windows_tz.py) kept in sync via update_windows_mappings.py, since Windows doesn’t use IANA tz names natively
• get_localzone_name() for just the timezone name string when a full tzinfo object isn’t needed
• Graceful fallback behavior when timezone detection is ambiguous or the environment is misconfigured (e.g. inside minimal Docker containers)

Common Use Cases

• Defaulting a scheduling library (cron-like jobs, calendar apps) to the user’s local timezone when none is explicitly configured
• Displaying timestamps to users in their own local time without asking them to select a timezone from a dropdown
• Logging or auditing systems that need to record events in local time alongside UTC
• CLI tools and desktop applications that need consistent, cross-platform timezone detection without shelling out to OS-specific commands

Under The Hood

Architecture - A thin dispatch layer in __init__.py (15 lines) selects between unix.py, win32.py at import time based on sys.platform, delegating all OS-specific detection logic to the platform module while sharing validation helpers in utils.py.

Tech Stack - Pure Python standard-library-only on Python 3.9+ (using zoneinfo from the stdlib), with pytz-deprecation-shim for backward compatibility with code still expecting pytz timezone objects; no compiled extensions.

Code Quality - Tests cover each platform’s detection path with mocked filesystem/registry state; windows_tz.py — a 736-line generated mapping table — is kept current via a dedicated update_windows_mappings.py script that pulls from Unicode CLDR data rather than being hand-maintained.

API Design - The entire library boils down to one function call, get_localzone(), that just works regardless of OS — there’s no configuration object or platform-conditional code required from the caller, which is exactly why so many other libraries pull it in as a dependency rather than reimplementing detection themselves.