pytz
IANA timezone database for Python — provides timezone objects for making naive datetime objects timezone-aware. pytz features: timezone() for IANA timezone lookup (e.g. 'US/Eastern', 'Europe/London'), utc for UTC timezone object, localize() for attaching timezone to naive datetime, normalize() for DST transition correction, astimezone() for timezone conversion, all_timezones list, common_timezones for frequently used zones, and timezone abbreviation lookup. Note: Python 3.9+ has zoneinfo in stdlib which largely supersedes pytz.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Pure timezone database library. No network calls — timezone data is bundled. Update pytz regularly for IANA database updates (governments change DST rules). No security concerns beyond keeping timezone data current.
⚡ Reliability
Best When
Legacy Python codebases requiring timezone support, or dependencies that still require pytz timezone objects — otherwise prefer stdlib zoneinfo on Python 3.9+.
Avoid When
Python 3.9+ (use zoneinfo), projects using arrow/pendulum (built-in TZ support), or new projects where stdlib zoneinfo is available.
Use Cases
- • Agent timezone-aware datetime — import pytz; from datetime import datetime; eastern = pytz.timezone('US/Eastern'); naive_dt = datetime(2024, 6, 15, 14, 30); aware_dt = eastern.localize(naive_dt); print(aware_dt) — '2024-06-15 14:30:00-04:00' — localized; agent creates timezone-aware datetime; localize() attaches timezone to naive datetime correctly handling DST
- • Agent UTC conversion — utc = pytz.utc; now_utc = datetime.now(utc); eastern = pytz.timezone('US/Eastern'); now_eastern = now_utc.astimezone(eastern); print(now_eastern) — UTC to Eastern; agent converts between timezones; astimezone() converts aware datetime; pytz.normalize() required after arithmetic on DST-aware datetimes
- • Agent list timezones — print(pytz.all_timezones[:5]) — all IANA zones; print(pytz.common_timezones[:5]) — frequently used; tz = pytz.timezone('America/New_York') — canonical name; agent lists available timezones; 'US/Eastern' is alias for 'America/New_York'; prefer canonical names
- • Agent DST handling — eastern = pytz.timezone('US/Eastern'); ambiguous_dt = datetime(2024, 11, 3, 1, 30); std = eastern.localize(ambiguous_dt, is_dst=False); dst = eastern.localize(ambiguous_dt, is_dst=True) — DST ambiguity; agent explicitly specifies DST during 'fall back' hour when 1:30 AM occurs twice; is_dst=None raises AmbiguousTimeError
- • Agent store UTC convert display — # Store in UTC; utc_dt = datetime.now(pytz.utc); db.save(utc_dt.isoformat()); # Display in user timezone; user_tz = pytz.timezone(user.timezone); display_dt = utc_dt.astimezone(user_tz) — UTC storage pattern; agent stores all times in UTC; converts to user timezone for display only
Not For
- • Python 3.9+ projects — use zoneinfo (stdlib) instead: from zoneinfo import ZoneInfo; datetime.now(ZoneInfo('US/Eastern')); no dependency needed
- • Arrow or pendulum users — both libraries include timezone support; no need for pytz separately
- • New projects — prefer zoneinfo for Python 3.9+; pytz is legacy but still widely used
Interface
Authentication
No auth — timezone database library.
Pricing
pytz is MIT licensed. IANA timezone database updates distributed via pip updates. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Never use tz=pytz.timezone('...') in datetime constructor — datetime(2024, 1, 1, tzinfo=eastern) is WRONG and produces incorrect UTC offsets for DST; always use eastern.localize(datetime(2024, 1, 1)) instead; this is the most common pytz mistake; tzinfo= parameter bypasses DST logic
- ⚠ normalize() required after timedelta arithmetic — eastern_dt + timedelta(hours=25) may cross DST boundary and have wrong offset; always: pytz.normalize(eastern_dt + timedelta(hours=25)) after any arithmetic on timezone-aware datetimes; normalize() re-applies correct DST offset
- ⚠ Timezone names are IANA not Windows — pytz.timezone('Eastern Standard Time') raises UnknownTimeZoneError; use IANA names: 'America/New_York' or 'US/Eastern'; agent code accepting user timezone strings: validate with try: pytz.timezone(tz_str) except UnknownTimeZoneError; common mistake with Windows system timezone names
- ⚠ AmbiguousTimeError during 'fall back' — when is_dst=None (default), localizing a time that exists twice raises AmbiguousTimeError; agent code processing logs from fall-back hour: use is_dst=False for standard time (after clock falls back); is_dst=True for DST time (before fallback); or trap AmbiguousTimeError
- ⚠ pytz timezone objects are not equal across calls — pytz.timezone('US/Eastern') == pytz.timezone('US/Eastern') is True (cached); but isinstance checks work; comparing pytz tz with zoneinfo tz returns False; agent code mixing pytz and zoneinfo: avoid mixing; pick one system
- ⚠ pytz is deprecated for Python 3.9+ — Python 3.9 added zoneinfo to stdlib; pytz still works but new code should use: from zoneinfo import ZoneInfo; datetime.now(ZoneInfo('America/New_York')); no localize() needed; ZoneInfo handles DST automatically with + operator; agent code targeting Python 3.9+: migrate to zoneinfo
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for pytz.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-06.