Unix Timestamps: The Complete Developer Reference

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, not counting leap seconds. It is a universal, timezone-agnostic way to represent a moment in time.

1700000000  →  November 14, 2023, 22:13:20 UTC

Timestamps are stored as integers (or floating-point for sub-second precision) and are independent of locale, timezone, or daylight saving time — which makes them the preferred format for APIs, databases, log files, and distributed systems.

Getting the Current Timestamp

// JavaScript — seconds
Math.floor(Date.now() / 1000)

// JavaScript — milliseconds (more common in JS)
Date.now()

// Python
import time
int(time.time())  # seconds

# Shell
date +%s

# SQL (PostgreSQL)
SELECT EXTRACT(EPOCH FROM NOW())::BIGINT;

Converting Timestamp to Human Date

// JavaScript
const ts = 1700000000;
const date = new Date(ts * 1000);  // JS uses milliseconds
date.toISOString();   // "2023-11-14T22:13:20.000Z"
date.toLocaleString();  // Local time string

// Python
from datetime import datetime, timezone
datetime.fromtimestamp(1700000000, tz=timezone.utc)
# datetime(2023, 11, 14, 22, 13, 20, tzinfo=datetime.timezone.utc)

# Human-readable
datetime.utcfromtimestamp(1700000000).strftime('%Y-%m-%d %H:%M:%S')

Converting Human Date to Timestamp

// JavaScript — always parse ISO strings with timezone
const ts = Date.parse("2024-01-15T12:00:00Z") / 1000;

// Python
from datetime import datetime, timezone
dt = datetime(2024, 1, 15, 12, 0, 0, tzinfo=timezone.utc)
int(dt.timestamp())

The Year 2038 Problem

Systems that store timestamps as a 32-bit signed integer will overflow on January 19, 2038, at 03:14:07 UTC — the maximum value for a 32-bit signed integer is 2,147,483,647 seconds. Most modern systems use 64-bit integers, which are safe until the year 292,277,026,596. Check any legacy C code, embedded systems, or databases using INT columns for timestamps.

Timezone Pitfalls

Unix timestamps are always UTC, but displaying them involves timezone conversion. Common mistakes:

Mixing local and UTC: new Date("2024-01-15") in JavaScript is parsed as UTC midnight, but new Date(2024, 0, 15) is local midnight. They differ by the user's UTC offset.
Daylight Saving Time: During DST transitions, a local clock can show the same time twice (fall back) or skip an hour entirely (spring forward). Never use local time for arithmetic — use UTC timestamps.
Database storage: Store timestamps as TIMESTAMPTZ in PostgreSQL or DATETIME with explicit UTC offset in MySQL. Avoid storing local times in databases.

Date Arithmetic with Timestamps

// Add 7 days to a timestamp
const now = Math.floor(Date.now() / 1000);
const oneWeekLater = now + (7 * 24 * 60 * 60);  // 604800 seconds

// Difference between two dates in days
const diff = Math.abs(ts2 - ts1);
const days = Math.floor(diff / 86400);

// Python
from datetime import timedelta
future = dt + timedelta(days=7)

Milliseconds vs Seconds

A consistent source of bugs: JavaScript's Date.now() and many browser APIs use milliseconds, while most backend systems, databases, and Unix tools use seconds. Always check the unit when consuming timestamps from external APIs.

// A 13-digit number is milliseconds; a 10-digit number is seconds
const isMs = timestamp.toString().length === 13;
const seconds = isMs ? Math.floor(timestamp / 1000) : timestamp;

Convert Timestamps Instantly

Use ToolsVito's Timestamp Converter to convert between Unix timestamps and human-readable dates, in any timezone, directly in your browser.