⚡ SmartDevTools

Unix Timestamps and Time Zones: A Developer's Guide

By SmarTech Apps · Published 2026-11-18 · 6 min read

A Unix timestamp is just a number: how much time has passed since midnight UTC on 1 January 1970. That simplicity is why it is everywhere, and also why bugs appear around it. The mistakes are rarely in the arithmetic. They come from mixing units, forgetting which zone a wall-clock time was in, or trusting a local clock that skips an hour.

What a timestamp actually is

The Unix epoch is 1970-01-01 00:00:00 UTC. A timestamp counts the seconds since then, ignoring leap seconds. The value 1700000000 is 2023-11-14 22:13:20 UTC. Nothing in that number says anything about a time zone, because an instant in time is the same everywhere. A time zone only matters when you display it to a person. That is the key idea: a timestamp identifies a moment, and a zone is a presentation choice.

Because a timestamp is a plain integer, comparing and subtracting is trivial, and sorting works as expected. That is the reason databases, log files, JWT claims and cookies all lean on it.

Seconds, milliseconds and microseconds

Different systems count in different units, and nothing in the number labels which one you have. Classic Unix tools, most databases and JWT claims use seconds. JavaScript's Date.now() and Java's System.currentTimeMillis() use milliseconds. Some tracing systems and Python's time_ns-based APIs use microseconds or nanoseconds.

For present-day dates you can tell them apart by length:

DigitsLikely unitExample
10Seconds1700000000
13Milliseconds1700000000000
16Microseconds1700000000000000
19Nanoseconds1700000000000000000

This heuristic holds for dates between 2001 and 2286. Outside that range the digit counts shift, and dates near 1970 in milliseconds can look like seconds. The classic symptom of getting it wrong is a date in January 1970 (seconds treated as milliseconds divided too far) or a year around 55,000 (milliseconds treated as seconds). The Epoch Time Converter auto-detects seconds versus milliseconds from the number of digits and converts in both directions, so it is a quick way to see which reading gives a sensible date.

UTC versus local time

UTC is the reference. Local time is UTC plus an offset that depends on the place and, often, the date. Store and transmit UTC, and convert to local time only at the edge, when rendering for a user. A server that writes local timestamps into a database will eventually collide with another server, another region or a daylight saving change.

Do not confuse a numeric offset with a zone. -05:00 is an offset: it fixes the difference from UTC for one instant. America/New_York is a zone: a set of rules that gives -05:00 in winter and -04:00 in summer. To schedule future events you need the zone, because the offset can change. For past events the offset is enough.

Daylight saving time pitfalls

Twice a year, local clocks jump. In the United States in 2024, clocks moved from 02:00 straight to 03:00 on 10 March, so the local time 02:30 never happened. In the autumn, 01:30 happens twice. Code that builds local times by hand can fail in both ways.

// TZ=America/New_York
new Date("2024-03-10T02:30:00").toString()
// "Sun Mar 10 2024 03:30:00 GMT-0400 (Eastern Daylight Time)"

The non-existent time silently moved forward an hour. Other consequences are less obvious:

To compare the same moment in several places, the Time Zone Converter uses IANA zone names, applies DST rules for the date you choose, and can show several target zones side by side. Pick a named zone rather than an abbreviation like EST, since abbreviations are ambiguous.

ISO 8601 and offsets in text

When you must write a time as text, use ISO 8601 / RFC 3339: 2023-11-14T22:13:20Z. The trailing Z means UTC; 2023-11-14T17:13:20-05:00 is the same instant with an offset. Both are unambiguous and sort lexicographically when the offset is the same. A string with no offset, like 2023-11-14T22:13:20, is ambiguous: it is a wall-clock time with no zone, and different programs will interpret it differently. Always include the offset when serialising instants.

JavaScript Date quirks

JavaScript's Date stores milliseconds since the epoch, so new Date(1700000000) is a mistake for seconds: multiply by 1000 first. Parsing is where most surprises live:

// TZ=America/New_York
new Date("2024-01-05").toISOString()
// "2024-01-05T00:00:00.000Z"   date-only string is read as UTC

new Date("2024-01-05T00:00").toISOString()
// "2024-01-05T05:00:00.000Z"   date-time without offset is read as local

Those two strings differ by only a few characters yet give instants five hours apart. Other quirks: months are zero-based (new Date(2024, 0, 5) is January), getYear is deprecated, and Date has no zone support beyond UTC and the system zone, so use Intl.DateTimeFormat with a timeZone option for display. An invalid date does not throw; it produces a Date whose time value is NaN.

Leap seconds and the Year 2038 problem

Unix time pretends every day has exactly 86,400 seconds. Real UTC sometimes inserts a leap second, and Unix time handles that by repeating or smearing a second rather than counting it, so the difference between two timestamps can differ from real elapsed seconds by a few seconds. That is fine for almost every application, but not for precise astronomy or measurement.

The Year 2038 problem is more practical. A signed 32-bit integer tops out at 2,147,483,647. As a timestamp, that is 2038-01-19 03:14:07 UTC, which you can confirm in Python with datetime.fromtimestamp(2147483647, timezone.utc). One second later a 32-bit signed counter wraps to a negative number, which reads as December 1901. Modern 64-bit systems and languages are not affected, but old embedded devices, file formats and database columns declared as 32-bit integers can be. For example, a MySQL TIMESTAMP column stops at that same moment. Anything that stores timestamps long-term, or computes dates decades ahead such as mortgages or certificates, should use 64-bit values.

A short checklist

  1. Store instants in UTC, as integers or ISO 8601 strings with an offset.
  2. Write the unit into the field name: created_at_ms, not created.
  3. Keep the zone name, not just the offset, for future events a person will attend.
  4. Convert to local time only when displaying.
  5. Test around DST changes and the end of the year.

Timestamps also appear in tokens: the exp and iat claims in a JWT are seconds since the epoch, which is covered in how JWTs work, and you can inspect them with the JWT Decoder. When a number looks odd, paste it into the epoch converter before debugging anything else.

Try the tools

Keep reading