Understanding Unix Timestamps and Epoch Time

You've seen them in logs, database records, API responses, and JWT tokens: a number like 1711843200. That's a Unix timestamp — a deceptively simple representation of a moment in time that underpins virtually every computer system on the planet. Here's everything you need to know.

What Is a Unix Timestamp?

A Unix timestamp (also called epoch time or POSIX time) is the number of seconds that have elapsed since January 1, 1970 at 00:00:00 UTC. This reference point — called the Unix epoch — was chosen when the Unix operating system was designed in the early 1970s.

The timestamp 1711843200, for example, represents March 31, 2024 at 00:00:00 UTC. Timestamps can also be negative — representing dates before 1970.

Seconds vs Milliseconds

This is one of the most common sources of bugs in timestamp handling. There are two conventions in widespread use:

A quick sanity check: a 10-digit number is seconds; a 13-digit number is milliseconds. If you pass a millisecond timestamp to a function expecting seconds, you'll get a date in the year 55,000 — a bug that's hard to miss but easy to make.

Getting the Current Timestamp

JavaScript

// Milliseconds (JavaScript native)
Date.now()               // 1711843200000

// Seconds
Math.floor(Date.now() / 1000)  // 1711843200

Python

import time

# Seconds (float)
time.time()          # 1711843200.123

# Seconds (integer)
int(time.time())     # 1711843200

Unix shell

date +%s     # 1711843200

SQL

-- PostgreSQL
SELECT EXTRACT(EPOCH FROM NOW());

-- MySQL
SELECT UNIX_TIMESTAMP();

Converting a Timestamp to a Human-Readable Date

JavaScript

const ts = 1711843200;
const date = new Date(ts * 1000);  // Note: multiply by 1000

console.log(date.toISOString());
// "2024-03-31T00:00:00.000Z"

console.log(date.toLocaleString());
// "3/31/2024, 12:00:00 AM" (locale-dependent)

Python

from datetime import datetime, timezone

ts = 1711843200
dt = datetime.fromtimestamp(ts, tz=timezone.utc)
print(dt.isoformat())
# "2024-03-31T00:00:00+00:00"

Common Pitfalls

The Year 2038 Problem

32-bit signed integers can store timestamps up to 2147483647, which corresponds to January 19, 2038. After this point, 32-bit systems roll over to negative values — the same class of bug as Y2K. Modern 64-bit systems are unaffected, but embedded systems and legacy databases using 32-bit integers are still at risk.

Timezone confusion

Unix timestamps are always UTC. The confusion happens when converting to local time — always be explicit about which timezone you're converting to. Never assume "local" means the same thing on every machine.

Daylight saving time

Because Unix timestamps are UTC, they are immune to DST changes. This is one of the strongest arguments for storing all times as timestamps and only converting to local time at the display layer.

Try It Now

Use the DateTime Tools on io9.me to convert any Unix timestamp to a human-readable date, or convert a date to its epoch value — instantly, in your browser.