All posts
June 7, 20265 min read

Unix timestamps and epoch time explained: seconds, milliseconds, and the 2038 problem

A Unix timestamp is one number: the count of seconds since midnight UTC on 1 January 1970, a moment called the epoch. That single integer is how most systems store and exchange time, because it is unambiguous and trivial to compare. Understanding what it does and does not encode prevents a whole class of bugs.

Seconds or milliseconds?

This is the most common mistake. Classic Unix time counts seconds, so a current timestamp is ten digits, like 1796000000. JavaScript's Date.now() and many JSON APIs count milliseconds, so they are thirteen digits, like 1796000000000. Multiply or divide by 1000 to convert. If a date comes out in 1970, you treated milliseconds as seconds; if it comes out fifty thousand years in the future, you did the reverse. Paste either into the Timestamp Converter and it shows you the human date both ways.

There is no time zone in a timestamp

A Unix timestamp is always UTC. It carries no offset, no daylight saving, no locale. The local time you see is produced when you format the number for display. This is a feature: store the timestamp, convert to the user's zone only at the edge. Bugs appear when code formats a timestamp in the server's local zone and assumes the viewer shares it. Store UTC, format late.

The epoch and the year 2038

The epoch is fixed at 1970-01-01T00:00:00Z. Timestamps before it are negative, which is legal and represents dates in the past. The famous year 2038 problem comes from storing the count in a signed 32-bit integer, which overflows on 19 January 2038 and wraps to a negative number, throwing the date back to 1901. The fix is to use 64-bit integers, which most modern systems already do, but old embedded devices and legacy database columns can still bite.

Practical conversions

  • To a timestamp from a date: take the UTC date and ask for seconds since epoch.
  • From a timestamp to a date: decide first whether the number is in seconds or milliseconds, then format in the zone you want to display.
  • Comparing two events: subtract the timestamps. The difference is a duration in seconds (or milliseconds), with no calendar math required.

When you are reading logs, debugging a token's exp claim, or lining up events across services, a timestamp is the cleanest common currency. If that token is a JWT, the JWT Decoder shows its iat and exp as both raw timestamps and readable dates, and What is actually inside a JWT explains the rest of the claims. For one-off conversions in either direction, keep the Timestamp Converter open.