A Unix timestamp is one of the simplest ways to record a moment: a single number. The trouble is that different systems count in different units. Mix seconds and milliseconds and your dates land in 1970 or tens of thousands of years in the future. This article explains the convention and how to handle it reliably.
What the number means
A Unix timestamp counts time elapsed since the Unix epoch: 00:00:00 UTC on 1 January 1970. Zero is that instant; negative values are earlier. Because the reference point is in UTC, a timestamp identifies the same moment everywhere on Earth. Time zones only come into play when you turn it into a calendar date and clock time for a person to read.
Unix time ignores leap seconds: every day is treated as exactly 86,400 seconds. That keeps arithmetic simple and is why you can subtract two timestamps to get a duration, with the caveat that the result can differ from atomic time by the leap seconds in between.
Seconds or milliseconds?
The original Unix convention counts whole seconds. Many newer platforms count milliseconds for extra precision. A few common examples:
| Environment | Call | Unit |
|---|---|---|
| JavaScript | Date.now(), date.getTime() | milliseconds |
| Java | System.currentTimeMillis() | milliseconds |
| Python | time.time() | seconds (as a float) |
| PHP | time() | seconds |
| Go | time.Now().Unix() / UnixMilli() | seconds / milliseconds |
| PostgreSQL | extract(epoch from now()) | seconds (with fraction) |
| MySQL | UNIX_TIMESTAMP() | seconds |
| Shell (GNU date) | date +%s | seconds |
Some systems go finer still: microseconds (16 digits for current dates) appear in some databases and logs, and nanoseconds (19 digits) in tracing and monitoring tools.
Telling them apart at a glance
Count the digits. Between September 2001 and November 2286, a seconds timestamp has exactly 10 digits. Milliseconds for the same range have 13. That is why the Daily Dev Tools epoch converter treats values with 12 or more digits as milliseconds.
The symptoms of getting it wrong are distinctive:
- Seconds read as milliseconds:
1700000000as milliseconds is about 20 days after the epoch, so you see a date in January 1970. - Milliseconds read as seconds:
1700000000000as seconds is roughly 53,900 years in the future, and many date libraries reject it as out of range.
Converting is a multiplication or division by 1,000. When going from milliseconds to seconds, decide whether you want to round down (Math.floor), which is the usual convention, or keep the fraction.
The year-2038 problem
Older systems store seconds in a signed 32-bit integer, which can count up to 2,147,483,647. That value is reached at 03:14:07 UTC on 19 January 2038. One second later, the number overflows to a large negative value, which reads as a date in December 1901. Most modern operating systems and languages use 64-bit time values, but embedded devices, old file formats and database columns declared as 32-bit integers can still be affected. Check the column types and binary formats you control.
Milliseconds were never stored in 32 bits in practice, since the current value already needs more than 40 bits.
Storing time safely
- Pick one unit per system and name it. Field names such as
expires_at_sorcreated_msprevent silent mix-ups. In APIs, document the unit next to every timestamp field. - Prefer native date types in databases. A
timestamptzcolumn in PostgreSQL, for example, stores an instant and handles conversion for you. Use integers when you need a compact, language-neutral value. - Use ISO 8601 for human-facing interchange.
2024-03-09T14:30:00Zis readable, sorts correctly as text and states its zone. - Store future local events with a zone name. A timestamp fixes a moment; it cannot express “9 a.m. local time on every working day” or survive a government changing its daylight-saving rules. Keep the IANA zone name, such as
Asia/KolkataorAmerica/New_York, alongside local appointments. - Use 64-bit integers for any integer timestamp column.
Displaying time to people
Convert to local time at the last moment, in the user's own time zone, and say which zone you used if it might be ambiguous. In browsers, Intl.DateTimeFormat formats dates in the user's locale and zone. Relative descriptions such as “3 hours ago” are friendly for recent events; switch to absolute dates for anything older than a few days so readers can place them.
A quick debugging routine
- Count the digits to guess the unit.
- Convert it with both interpretations and see which date is plausible.
- Check whether the producer used UTC or a local clock without an offset.
- Trace where the value was multiplied or divided by 1,000 and make sure it happened exactly once.