Unix Timestamps Explained for Developers

A Unix timestamp is the number of seconds elapsed since the Unix epoch — 1970-01-01T00:00:00Z (midnight UTC on January 1st, 1970). It is the standard representation of a point in time in operating systems, databases, log files, and APIs. Understanding how timestamps work prevents the most common datetime bugs: timezone confusion, milliseconds vs seconds mismatches, and the 2038 problem.

The Unix epoch

The epoch is an agreed-upon origin point. Time before it produces negative timestamps (e.g., 1969-12-31 is timestamp -86400). The number is always expressed in UTC, meaning it has no timezone. Converting to a human-readable date requires knowing what timezone to display — the timestamp itself carries no timezone information.

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

// From timestamp to date
new Date(1_700_000_000 * 1000).toISOString();
// → "2023-11-14T22:13:20.000Z"

Seconds vs milliseconds

This is the most common source of timestamp bugs. Unix time is canonically in seconds, but JavaScript's Date.now() and many APIs return milliseconds. At the time of writing, the current Unix timestamp in seconds is around 1.7 billion; in milliseconds it is 1.7 trillion. If you store a millisecond value where seconds are expected, dates will show up in the year 56,000.

Working with timestamps in JavaScript

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

// Parse a timestamp into a Date
const date = new Date(1_700_000_000 * 1000);
console.log(date.toISOString());    // UTC string
console.log(date.toLocaleString()); // Local timezone string

// Future timestamp (24 hours from now)
const tomorrow = Math.floor(Date.now() / 1000) + 86400;

// Check if a timestamp is expired
function isExpired(ts) {
  return ts < Math.floor(Date.now() / 1000);
}

Working with timestamps in Python

import time
from datetime import datetime, timezone

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

# Parse timestamp to datetime (always UTC-aware)
dt = datetime.fromtimestamp(1_700_000_000, tz=timezone.utc)
print(dt.isoformat())  # 2023-11-14T22:13:20+00:00

# datetime to timestamp
ts = int(dt.timestamp())

Timezones and timestamps

A Unix timestamp is always UTC — there is no such thing as "a Unix timestamp in Eastern time." Timezone only matters when converting to or from a human-readable string. The two main mistakes:

• Storing local time as if it were UTC — a timestamp generated on a machine set to UTC-5 will be off by 5 hours if naively treated as UTC.
• Displaying UTC timestamps without conversion — users see the wrong hour unless you convert to their local timezone in the UI.

Best practice: store and transmit UTC timestamps everywhere. Convert to the user's local timezone only at display time, using the browser's Intl.DateTimeFormat or a library like date-fns-tz.

The Year 2038 problem

On January 19, 2038 at 03:14:07 UTC, 32-bit signed integer Unix timestamps will overflow from 2147483647 to -2147483648, wrapping clocks back to 1901. This affects legacy embedded systems, 32-bit C code, and old database schemas using INT for timestamps. Modern 64-bit systems can represent dates billions of years into the future. The fix is to use 64-bit integers for timestamps — which all modern languages and databases already do by default.