Understanding Unix Timestamps

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, 00:00:00 UTC — a point in time known as the Unix Epoch.

For example, the timestamp 1700000000 corresponds to November 14, 2023 at 22:13:20 UTC.

Unix timestamps are timezone-independent — they always represent a moment in UTC. Converting to a local time is done at display time, not at storage time.

Why are Unix timestamps used?

• Simple comparison — to check if event A happened before event B, just compare two numbers
• No timezone ambiguity — a timestamp is always UTC, so there is no confusion across timezones
• Compact storage — a single integer takes much less space than a formatted date string
• Easy arithmetic — adding 86400 to a timestamp always gives you exactly 24 hours later
• Universal support — every programming language and database understands Unix timestamps

Seconds vs milliseconds

The standard Unix timestamp is in seconds. However, many languages and APIs (especially JavaScript) use milliseconds.

A quick way to tell: if the timestamp has 10 digits, it is in seconds. If it has 13 digits, it is in milliseconds.

Working with timestamps in code

In JavaScript:

// Current timestamp in seconds
const seconds = Math.floor(Date.now() / 1000);

// Current timestamp in milliseconds
const ms = Date.now();

// Convert timestamp to Date
const date = new Date(1700000000 * 1000);
console.log(date.toISOString()); // "2023-11-14T22:13:20.000Z"

// Convert Date to timestamp
const ts = Math.floor(new Date('2023-11-14').getTime() / 1000);

In Python:

import time
from datetime import datetime, timezone

# Current timestamp
ts = int(time.time())

# Convert timestamp to datetime (UTC)
dt = datetime.fromtimestamp(1700000000, tz=timezone.utc)
print(dt.isoformat())  # "2023-11-14T22:13:20+00:00"

# Convert datetime to timestamp
ts = int(datetime(2023, 11, 14, tzinfo=timezone.utc).timestamp())

In SQL (PostgreSQL):

-- Current timestamp
SELECT EXTRACT(EPOCH FROM NOW())::BIGINT;

-- Convert timestamp to date
SELECT TO_TIMESTAMP(1700000000);

-- Convert date to timestamp
SELECT EXTRACT(EPOCH FROM '2023-11-14'::TIMESTAMP WITH TIME ZONE);

Timezones and timestamps

A Unix timestamp is always in UTC. When displaying it to users, you convert it to their local timezone. This separation of concerns is important:

• Store timestamps in UTC (as a Unix timestamp or UTC datetime)
• Display timestamps in the user's local timezone
• Never store a timestamp with a timezone offset baked in

The Year 2038 problem

Systems that store Unix timestamps as a 32-bit signed integer will overflow on January 19, 2038 at 03:14:07 UTC. This is similar to the Y2K bug. Modern systems use 64-bit integers, which will not overflow for billions of years. If you are building anything new, always use 64-bit timestamps.