Time Zones, UTC and Unix Time

One moment in time has many local names. Handling dates well comes down to keeping the moment and its local display apart, and knowing which rules turn one into the other.

UTC and GMT

Coordinated Universal Time (UTC) is the reference time scale that civil clocks around the world are set from. Atomic clocks keep it, and leap seconds have kept it close to the Earth's rotation. Greenwich Mean Time (GMT) is the older astronomical time at Greenwich in London. The two stay within a second of each other, so casual use treats them as the same. In software, use UTC. Today GMT is mostly the name of a zone: the United Kingdom uses GMT in winter and British Summer Time (UTC+1) in summer. UTC itself never shifts for daylight saving.

Offsets and time zone names

An offset is a fixed distance from UTC, such as -05:00 or +05:30. A time zone is a region's full set of rules: which offset applied at which time, including daylight saving and past political changes. The IANA time zone database (also called tzdata) names zones after a region and a representative city, for example America/New_York, Europe/London, Asia/Tokyo and Asia/Kolkata.

The distinction matters because one zone uses different offsets during the year. Noon UTC on two dates, converted to America/New_York:

2024-01-15T12:00Z  ->  2024-01-15T07:00:00-05:00  (EST)
2024-07-01T12:00Z  ->  2024-07-01T08:00:00-04:00  (EDT)

An offset alone cannot tell you what next month's offset will be. Abbreviations are worse: IST is used for India, Ireland and Israel. Use IANA names in code.

Daylight saving time

Daylight saving time (DST) moves local clocks forward, usually by one hour, in spring and back again in autumn. Each region picks its own dates, many use no DST at all, and governments change the rules, so the tz database is updated regularly and code should never hard-code transition dates. When clocks spring forward, one local hour never happens. When they fall back, one local hour happens twice.

One instant on five clocks

This Python snippet converts the fixed instant 2024-03-10T06:30:00Z with the standard zoneinfo module:

from datetime import datetime, timezone
from zoneinfo import ZoneInfo

t = datetime(2024, 3, 10, 6, 30, tzinfo=timezone.utc)
for name in ["UTC", "America/New_York", "Europe/London",
             "Asia/Tokyo", "Asia/Kolkata"]:
    print(name, t.astimezone(ZoneInfo(name)).isoformat())
ZoneLocal timeAbbreviation
UTC2024-03-10T06:30:00+00:00UTC
America/New_York2024-03-10T01:30:00-05:00EST
Europe/London2024-03-10T06:30:00+00:00GMT
Asia/Tokyo2024-03-10T15:30:00+09:00JST
Asia/Kolkata2024-03-10T12:00:00+05:30IST

Kolkata shows that offsets are not always whole hours. New York is still on standard time here, but only for another half hour: one hour later, at 07:30 UTC, the same code prints 2024-03-10T03:30:00-04:00.

The DST gap, computed

On 2024-03-10 in New York, local clock readings from 02:00 to 02:59:59 never occurred. Converting the two UTC seconds on either side of the change shows the jump:

2024-03-10T06:59:59Z  ->  2024-03-10T01:59:59-05:00
2024-03-10T07:00:00Z  ->  2024-03-10T03:00:00-04:00

If code builds the missing time 02:30 anyway, zoneinfo raises no error. It applies the offset from before the change, and a round trip through UTC comes back as a different clock reading:

local, as built:  2024-03-10T02:30:00-05:00
to UTC:           2024-03-10T07:30:00+00:00
back to local:    2024-03-10T03:30:00-04:00

Autumn has the opposite problem. On 2024-11-03 the reading 01:30 happened twice in New York, first at -04:00 (05:30 UTC) and then at -05:00 (06:30 UTC). Python chooses with the fold attribute, 0 for the first and 1 for the second. Calendar math is affected too: adding one day to noon on 9 March 2024 in New York gives noon on 10 March, yet only 23 hours passed in real time.

ISO 8601 timestamps

ISO 8601 writes the largest unit first. When strings share the same offset and precision, sorting them as text also sorts them in time order.

ExampleWhat it says
2024-03-10A calendar date
2024-03-10T06:30:00ZAn instant in UTC; Z means offset zero
2024-03-10T01:30:00-05:00The same instant as New York local time
2024-03-10T06:30:00.250ZAn instant with milliseconds
PT1H30MA duration of one hour and thirty minutes
2024-03-10T06:30:00A clock reading with no offset, which is not an instant

The last row is the trap. Without Z or an offset, a timestamp is only a wall-clock reading and could mean many different moments. Even with an offset, the string records the moment but not the zone, so it cannot tell you which rules apply later.

Unix time

Unix time counts the seconds since 1970-01-01T00:00:00Z, the Unix epoch, and leaves leap seconds out. It is one integer with no time zone at all, which makes it simple to store and compare. Some values computed with datetime.fromtimestamp(n, timezone.utc):

0           ->  1970-01-01T00:00:00+00:00
1000000000  ->  2001-09-09T01:46:40+00:00
1710052200  ->  2024-03-10T06:30:00+00:00

JavaScript's Date.now() and many APIs count milliseconds instead, which turns the last example into 1710052200000. A 13-digit value for a recent date is almost always milliseconds. Binary formats sometimes store it in hexadecimal; see number bases.

The year 2038 problem

Older systems store Unix time in a signed 32-bit integer. Its largest value is 2147483647 (2^31 - 1), and Python converts it to 2038-01-19T03:14:07+00:00. One second later the value wraps to -2147483648, which reads as 1901-12-13T20:45:52+00:00. Most current platforms use 64-bit time, but embedded devices, old file formats and 32-bit database columns can still hit this limit.

A checklist for storing and showing time

  • Store past events as UTC instants or Unix time. A log entry or an order time is a fixed moment.
  • Convert at the edge. Turn UTC into local time only when you show it to a person, and turn input into UTC as soon as you receive it.
  • For future events tied to a place, such as a 09:00 meeting in Berlin next spring, store the local date and time plus the IANA zone name. If DST rules change before then, a UTC value computed today would be wrong.
  • Send timestamps in APIs as ISO 8601 with Z or an explicit offset, never as bare local times.
  • Keep tz data current in your operating system, runtime and libraries.
  • Never assume a day has 24 hours, or that each local time occurs exactly once. Scheduled jobs set for 02:30 local time can be skipped or run twice on change days, depending on the scheduler; cron expressions has more on scheduling.