Eric Campbell 6 min read Engineering

Date and Time: Time Zones, UTC, and Libraries

Time handling has a well-earned reputation as one of programming's most treacherous domains. The complexity stems from a collision between human political systems and the need for precise...

Key Insights

  • Store all timestamps in UTC and convert to local time only at display boundaries—this single rule prevents the majority of time-related bugs in production systems.
  • Time zones and offsets are not interchangeable: offsets are fixed snapshots, while time zones encode historical and future rules including DST transitions and political changes.
  • Recurring events are the exception to the UTC rule—store them as local time plus IANA zone identifier to correctly handle DST transitions and zone rule changes.

The Complexity of Time in Software

Time handling has a well-earned reputation as one of programming’s most treacherous domains. The complexity stems from a collision between human political systems and the need for precise computation. Consider what your code must handle:

  • Daylight Saving Time transitions where 2:30 AM either doesn’t exist or occurs twice
  • Leap seconds that occasionally add a 61st second to a minute
  • Countries that change their UTC offset for political reasons (Samoa skipped December 30, 2011 entirely)
  • Time zones that differ by non-hour amounts (Nepal is UTC+5:45)
  • Historical changes to zone rules that affect how past timestamps should be interpreted

The consequences of getting this wrong range from annoying (meetings scheduled at wrong times) to severe (financial transactions with incorrect timestamps, medication dosing errors in healthcare systems, legal documents with disputed dates). A 2020 incident at a major airline caused widespread booking failures when their system mishandled a DST transition.

UTC as Your Source of Truth

UTC (Coordinated Universal Time) is the foundation of sane time handling. It’s a continuous, unambiguous time standard with no daylight saving adjustments. Every instant in time maps to exactly one UTC timestamp.

A common misconception: UTC is not the same as GMT. GMT is a time zone (used in the UK during winter), while UTC is a time standard. They often show the same time, but GMT observes daylight saving in some contexts while UTC never does.

The rule is simple: store UTC, display local. Your database should contain UTC timestamps, and conversion to the user’s local time happens at the application boundary.

-- PostgreSQL schema example
CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    -- TIMESTAMP WITH TIME ZONE stores as UTC internally
    starts_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Insert with explicit UTC
INSERT INTO events (name, starts_at) 
VALUES ('Product Launch', '2024-03-15 14:00:00+00');

-- Or convert from local time at insert
INSERT INTO events (name, starts_at) 
VALUES ('Team Meeting', '2024-03-15 09:00:00 America/New_York');

When accepting user input, convert to UTC immediately:

from datetime import datetime
from zoneinfo import ZoneInfo

def store_event_time(local_time_str: str, user_timezone: str) -> datetime:
    """Convert user's local time input to UTC for storage."""
    user_tz = ZoneInfo(user_timezone)
    
    # Parse the local time (naive datetime)
    local_dt = datetime.strptime(local_time_str, "%Y-%m-%d %H:%M")
    
    # Attach the user's timezone
    local_aware = local_dt.replace(tzinfo=user_tz)
    
    # Convert to UTC for storage
    utc_dt = local_aware.astimezone(ZoneInfo("UTC"))
    
    return utc_dt

# User in New York enters "2024-03-15 09:00"
utc_timestamp = store_event_time("2024-03-15 09:00", "America/New_York")
# Stored as: 2024-03-15 14:00:00+00:00

The exception to UTC storage is recurring events, which we’ll address later.

Understanding Time Zones and Offsets

This distinction trips up even experienced developers. An offset like -05:00 tells you the difference from UTC at a specific moment. A time zone like America/New_York is a named region with rules about when offsets change.

New York is -05:00 in winter and -04:00 in summer. If you store only the offset, you lose the ability to correctly interpret future dates or handle historical queries when DST rules change.

from datetime import datetime
from zoneinfo import ZoneInfo

# The same instant, different representations
utc_instant = datetime(2024, 7, 15, 18, 0, tzinfo=ZoneInfo("UTC"))

zones = ["America/New_York", "Europe/London", "Asia/Tokyo", "Australia/Sydney"]

for zone_name in zones:
    local = utc_instant.astimezone(ZoneInfo(zone_name))
    print(f"{zone_name}: {local.strftime('%Y-%m-%d %H:%M %Z (UTC%z)')}")

# Output:
# America/New_York: 2024-07-15 14:00 EDT (UTC-0400)
# Europe/London: 2024-07-15 19:00 BST (UTC+0100)
# Asia/Tokyo: 2024-07-16 03:00 JST (UTC+0900)
# Australia/Sydney: 2024-07-16 04:00 AEST (UTC+1000)

DST transitions create genuinely ambiguous situations:

from datetime import datetime
from zoneinfo import ZoneInfo

# November 3, 2024: US clocks fall back at 2 AM
# 1:30 AM occurs TWICE in New York

eastern = ZoneInfo("America/New_York")

# The first 1:30 AM (during EDT, -04:00)
first_130 = datetime(2024, 11, 3, 1, 30, fold=0, tzinfo=eastern)

# The second 1:30 AM (during EST, -05:00)
second_130 = datetime(2024, 11, 3, 1, 30, fold=1, tzinfo=eastern)

print(f"First 1:30 AM in UTC:  {first_130.astimezone(ZoneInfo('UTC'))}")
print(f"Second 1:30 AM in UTC: {second_130.astimezone(ZoneInfo('UTC'))}")

# Output:
# First 1:30 AM in UTC:  2024-11-03 05:30:00+00:00
# Second 1:30 AM in UTC: 2024-11-03 06:30:00+00:00

The fold parameter (Python 3.6+) disambiguates these cases. Without explicit handling, your code makes an implicit choice that may not match user intent.

Library Landscape by Language

Modern languages have converged on similar designs, influenced heavily by Joda-Time’s concepts. Here’s what you should use:

Java: java.time (Java 8+). Avoid java.util.Date entirely.

import java.time.*;
import java.time.format.DateTimeFormatter;

// Parse user input with explicit zone
ZonedDateTime userTime = ZonedDateTime.of(
    LocalDateTime.of(2024, 3, 15, 9, 0),
    ZoneId.of("America/New_York")
);

// Convert to UTC for storage
Instant utcInstant = userTime.toInstant();

// Convert back for display in different zone
ZonedDateTime tokyoTime = utcInstant.atZone(ZoneId.of("Asia/Tokyo"));

System.out.println("UTC: " + utcInstant);
System.out.println("Tokyo: " + tokyoTime.format(DateTimeFormatter.ISO_ZONED_DATE_TIME));

Python: datetime with zoneinfo (Python 3.9+). For older versions, use pytz but be aware of its non-standard API for localization.

JavaScript: The Temporal API is the future but not yet widely available. Until then, use Luxon or date-fns-tz. Avoid moment.js (deprecated) and the native Date object for anything complex.

import { DateTime } from 'luxon';

// Create in user's zone
const userTime = DateTime.fromObject(
  { year: 2024, month: 3, day: 15, hour: 9 },
  { zone: 'America/New_York' }
);

// Convert to UTC
const utcTime = userTime.toUTC();

// Convert to another zone for display
const tokyoTime = userTime.setZone('Asia/Tokyo');

console.log(`User (NY): ${userTime.toISO()}`);
console.log(`UTC: ${utcTime.toISO()}`);
console.log(`Tokyo: ${tokyoTime.toISO()}`);

C#: NodaTime is superior to the built-in DateTime/DateTimeOffset. It enforces correct handling through its type system.

Rust: chrono with chrono-tz provides comprehensive timezone support with Rust’s safety guarantees.

Common Pitfalls and How to Avoid Them

Parsing ambiguous strings: Never parse a datetime string without knowing its timezone context.

# WRONG: Ambiguous, assumes system timezone
from datetime import datetime
dt = datetime.strptime("2024-03-15 09:00", "%Y-%m-%d %H:%M")

# RIGHT: Explicit timezone from user context
from zoneinfo import ZoneInfo
dt = datetime.strptime("2024-03-15 09:00", "%Y-%m-%d %H:%M")
dt = dt.replace(tzinfo=ZoneInfo(user_timezone))

Comparing datetimes: Always compare in UTC or ensure both datetimes are timezone-aware.

from datetime import datetime
from zoneinfo import ZoneInfo

# These represent the same instant
ny_time = datetime(2024, 3, 15, 10, 0, tzinfo=ZoneInfo("America/New_York"))
london_time = datetime(2024, 3, 15, 14, 0, tzinfo=ZoneInfo("Europe/London"))

# Comparison works correctly with aware datetimes
print(ny_time == london_time)  # True

# DANGER: Comparing naive and aware raises TypeError (Python 3)
# In some languages, it silently gives wrong results

Serialization: Always use ISO 8601 with explicit offset or ‘Z’ suffix for UTC.

from datetime import datetime
from zoneinfo import ZoneInfo

utc_now = datetime.now(ZoneInfo("UTC"))

# Correct ISO 8601 formats
print(utc_now.isoformat())  # 2024-03-15T14:30:00+00:00
print(utc_now.strftime("%Y-%m-%dT%H:%M:%SZ"))  # 2024-03-15T14:30:00Z

# For APIs, prefer the 'Z' suffix for UTC (more universally parsed)

Practical Recommendations

Follow this checklist for every project handling dates and times:

  1. Store UTC: All timestamps in your database should be UTC. Use TIMESTAMPTZ in PostgreSQL, DATETIME with UTC convention in MySQL.

  2. Display local: Convert to user’s timezone only at the presentation layer. Store user timezone preferences as IANA identifiers (America/New_York), never as offsets.

  3. Use IANA zone names: These are the America/New_York style identifiers maintained by IANA. They encode all historical and current rules.

  4. Keep tz databases updated: Your runtime’s timezone database needs regular updates. Political changes happen—Russia has changed its timezone rules multiple times in the past decade.

  5. Test edge cases: Include DST transition dates in your test suite. Test the “spring forward” gap and “fall back” overlap scenarios.

  6. Handle recurring events differently: For a “9 AM daily meeting,” store the local time (09:00) plus the IANA zone (America/New_York). Calculate each occurrence dynamically. This ensures the meeting stays at 9 AM local time even across DST transitions.

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

# Recurring event: 9 AM New York time, daily
def get_next_occurrences(local_hour: int, zone_name: str, count: int):
    zone = ZoneInfo(zone_name)
    today = datetime.now(zone).replace(hour=local_hour, minute=0, second=0, microsecond=0)
    
    occurrences = []
    current = today
    for _ in range(count):
        # Store the UTC instant for this occurrence
        occurrences.append(current.astimezone(ZoneInfo("UTC")))
        # Move to next day in LOCAL time, then recalculate
        next_local = (current + timedelta(days=1)).replace(hour=local_hour)
        current = next_local
    
    return occurrences

Time handling is genuinely hard, but these patterns will prevent the vast majority of bugs. Store UTC, use proper libraries, respect the distinction between zones and offsets, and test your edge cases. Your future self—debugging a production incident at 2 AM during a DST transition—will thank you.

Liked this? There's more.

Every week: one practical technique, explained simply, with code you can use immediately.