SpunkArt
Data, text and encoding

Unix timestamps: converting epoch time to dates

A Unix timestamp counts the seconds since midnight UTC on 1 January 1970. It is one plain number with no time zone, which is why databases, logs and APIs love it. People cannot read it, though, so here is how to convert it both ways and avoid the usual traps.

Timestamp to date

Date to timestamp

Landmark timestamps

A few reference points make it easy to sanity-check a number at a glance. All are UTC.

SecondsDate and time (UTC)Note
01970-01-01 00:00:00The epoch
86,4001970-01-02 00:00:00One day = 24 × 60 × 60 seconds
1,000,000,0002001-09-09 01:46:40The first 10-digit timestamp
1,700,000,0002023-11-14 22:13:20A Tuesday
1,893,456,0002030-01-01 00:00:00Start of 2030
2,147,483,6472038-01-19 03:14:07Largest signed 32-bit value

Seconds or milliseconds?

Unix tools, most databases and JWTs count seconds. JavaScript’s Date.now(), Java’s System.currentTimeMillis() and many JSON APIs count milliseconds. A quick test is the digit count: a current timestamp in seconds has 10 digits; in milliseconds it has 13. Mixing them up gives dramatic errors:

  • Reading 1700000000 as milliseconds gives 1970-01-20, about 19.7 days after the epoch.
  • Reading 1700000000000 as seconds gives a year far beyond 50,000.

If a converted date lands in January 1970 or tens of thousands of years ahead, the unit is wrong.

Converting by hand and in code

  1. Divide the seconds by 86,400 to get whole days since 1970-01-01, and keep the remainder.
  2. Turn the remainder into hours (÷ 3,600), then minutes (÷ 60), then seconds.
  3. Count forward that many days on the calendar, allowing for leap years. This step is why everyone uses a library.

Worked example for 1700000000. 1,700,000,000 ÷ 86,400 = 19,675 whole days with 80,000 seconds left. 80,000 seconds = 22 hours (79,200) + 13 minutes (780) + 20 seconds. Day 19,675 after the epoch is 2023-11-14, so the result is 22:13:20 UTC on that date.

date -u -d @1700000000          # GNU/Linux
date -u -r 1700000000           # macOS and BSD
python3 -c "import datetime as d; print(d.datetime.fromtimestamp(1700000000, d.timezone.utc))"
new Date(1700000000 * 1000).toISOString()   // JavaScript

Time zones and ISO 8601

A timestamp is the same instant everywhere; only its display changes. 1700000000 is 22:13:20 UTC, 17:13:20 at UTC−5, and 03:43:20 the next day at UTC+5:30. When you write a date as text, use ISO 8601 with an explicit offset, such as 2023-11-14T22:13:20Z or 2023-11-14T17:13:20-05:00. A date-time without an offset is ambiguous: JavaScript reads "2030-01-01T00:00" as local time but "2030-01-01" as UTC. The tool above treats both as UTC to stay predictable.

The year 2038 problem

Systems that store the count in a signed 32-bit integer run out at 2,147,483,647, which is 03:14:07 UTC on 19 January 2038. One second later the value wraps to a large negative number, which those systems read as a date in December 1901. Modern operating systems and languages use 64-bit time, but old file formats, embedded devices and database columns declared as 32-bit integers can still fail. Check the column type before you store timestamps.

Questions

Does Unix time include leap seconds?

No. Every Unix day is exactly 86,400 seconds, and leap seconds are absorbed by the clock. For everyday software this does not matter.

Can a timestamp be negative?

Yes. Negative values are dates before 1970; −86,400 is 1969-12-31 00:00:00 UTC.

Which time zone does the tool use?

It shows UTC and your browser’s own time zone. It sends nothing anywhere.