A Unix timestamp (also called epoch time or POSIX time) is the number of seconds that have passed since 00:00:00 UTC on 1 January 1970, a moment known as the Unix epoch. It's a single number that identifies the same instant everywhere on Earth, which is why databases, logs, and APIs love it.
Seconds or milliseconds?
Different systems count in different units, and mixing them up is the most common timestamp bug. A quick way to tell them apart is by length:
- 10 digits (like 1700000000) is almost always seconds. This is what Unix systems, PHP time(), and many APIs use.
- 13 digits (like 1700000000000) is almost always milliseconds. JavaScript's Date.now() and Java's System.currentTimeMillis() return this.
- 16 digits suggests microseconds, and 19 digits nanoseconds.
- Passing seconds where milliseconds are expected lands you in January 1970; the reverse lands tens of thousands of years in the future.
Converting in code
// JavaScript (Date expects milliseconds)
new Date(1700000000 * 1000).toISOString()
// "2023-11-14T22:13:20.000Z"
# Python
from datetime import datetime, timezone
datetime.fromtimestamp(1700000000, tz=timezone.utc)
# 2023-11-14 22:13:20+00:00
# Shell (GNU date)
date -u -d @1700000000
A timestamp has no time zone
A Unix timestamp is an instant in time, not a calendar date. Time zones only matter when you display it. Best practice is to store and transmit timestamps (or UTC ISO 8601 strings such as 2023-11-14T22:13:20Z) and convert to the viewer's time zone at the last moment.
Common bugs and how to avoid them
- Adding 86,400 seconds to mean "one day later". Days aren't always 24 hours in a local time zone that observes daylight saving. Use a date library for calendar arithmetic.
- Storing local time without an offset, which makes the value ambiguous or wrong when servers move regions.
- Comparing a seconds value to a milliseconds value.
- Treating timestamps as strings and sorting them lexicographically.
- Ignoring leap seconds: Unix time doesn't count them, so it is not an exact count of elapsed SI seconds.
The Year 2038 problem
Systems that store Unix time in a signed 32-bit integer overflow at 03:14:07 UTC on 19 January 2038, wrapping to a negative number that is interpreted as a date in 1901. Modern systems use 64-bit values, which push the limit billions of years away, but embedded devices and old databases may still be at risk.
Rule of thumb
Use UTC everywhere internally, use 64-bit integers or ISO 8601 strings for storage, and convert to a local time zone only when showing a time to a person.
Frequently asked questions
What is a Unix timestamp?
It is the number of seconds since 1 January 1970 00:00:00 UTC, used to represent a specific moment in time as a single number.
How can I tell if a timestamp is in seconds or milliseconds?
Count the digits. About 10 digits is seconds; about 13 digits is milliseconds.
Does a Unix timestamp include a time zone?
No. It represents a universal instant. A time zone is applied only when converting it to a human-readable local date.
What is the Year 2038 problem?
Signed 32-bit Unix time overflows on 19 January 2038. Systems using 64-bit timestamps aren't affected.
Try it: Unix Timestamp Converter — free, runs in your browser, nothing is uploaded.
Originally published at ilovekit.app.
