Unix timestamp

The basics

Unix time counts seconds from the epoch and ignores leap seconds, so every day is exactly 86,400 seconds. A few reference points:

Timestamp	Moment (UTC)
0	1970-01-01T00:00:00Z
1700000000	2023-11-14T22:13:20Z
2147483647	2038-01-19T03:14:07Z

Timestamps before 1970 are negative. A timestamp carries no time zone. It is always UTC, and the zone only matters when you display it.

Seconds versus milliseconds

Different systems use different units, and mixing them up is the most common time bug.

• Seconds: 10 digits today (1700000000). Used by most Unix tools, many APIs and the time claims in JWTs.
• Milliseconds: 13 digits (1700000000000). Used by JavaScript’s Date.now() and Java’s System.currentTimeMillis().
• Microseconds and nanoseconds: 16 and 19 digits, found in databases and tracing systems.

If a converted date lands in January 1970, you passed milliseconds to something expecting seconds. If it lands tens of thousands of years in the future, you did the opposite.

Converting in common languages

date -u -d @1700000000                                   # GNU date
date -u -r 1700000000                                    # macOS / BSD date
new Date(1700000000 * 1000).toISOString()                // JavaScript
datetime.fromtimestamp(1700000000, tz=timezone.utc)      # Python

The output as text is usually an ISO 8601 / RFC 3339 string.

The Year 2038 problem

A signed 32-bit integer tops out at 2147483647, which is 03:14:07 UTC on 19 January 2038. Systems still storing timestamps in 32 bits will overflow at that moment. Modern platforms use 64-bit values, which are good for billions of years, but old embedded devices, file formats and database columns can still be affected.

Common pitfalls

• Parsing in local time. Converting a date string without stating its zone gives different timestamps on different machines.
• Floating-point drift. Fractional seconds stored as floats can lose precision. Prefer integers in a smaller unit.
• Assuming leap seconds count. They do not, so Unix time can differ from an atomic-clock count by the number of leap seconds inserted since 1972.
• Using local time for comparisons. Compare and store timestamps in UTC, and convert to a zone only for display.