Unix Timestamps and Time Zones: A Developer's Guide
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:
| Digits | Likely unit | Example |
|---|---|---|
| 10 | Seconds | 1700000000 |
| 13 | Milliseconds | 1700000000000 |
| 16 | Microseconds | 1700000000000000 |
| 19 | Nanoseconds | 1700000000000000000 |
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:
- A day is not always 24 hours. Adding
86400seconds to "tomorrow at 9:00" will be an hour off across a change. - A daily job scheduled at 02:30 local time may be skipped or run twice. See cron expressions explained, and run schedules in UTC where you can.
- Not every zone shifts by an hour, and some use 30 or 45-minute offsets. Rules also change by government decree, so keep the tz database updated.
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
- Store instants in UTC, as integers or ISO 8601 strings with an offset.
- Write the unit into the field name:
created_at_ms, notcreated. - Keep the zone name, not just the offset, for future events a person will attend.
- Convert to local time only when displaying.
- 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.