Understanding Unix Timestamps

Unix timestamps appear everywhere: logs, databases, message queues, analytics pipelines, and API payloads. They are compact and portable, but they also hide timezone assumptions that cause expensive debugging sessions. This article explains how timestamps work and how to handle them with fewer surprises.

1. 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 — the "Unix Epoch." It is a universal, timezone-independent way to represent a point in time as a single integer.

2. Seconds vs Milliseconds

One of the most frequent bugs in timestamp handling is confusing seconds-based timestamps with milliseconds-based timestamps:

Quick sanity check: a 10-digit number is seconds, 13-digit is milliseconds. If your year comes out as 2525, you likely passed milliseconds where seconds were expected.

3. Converting Timestamps in Code

JavaScript

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

// Timestamp → Date string
const date = new Date(1741824000 * 1000);
console.log(date.toISOString()); // "2026-03-13T00:00:00.000Z"
console.log(date.toLocaleString('en-US', { timeZone: 'America/New_York' }));

// Date string → Timestamp
const ts = Math.floor(new Date('2026-03-13T00:00:00Z').getTime() / 1000);
console.log(ts); // 1741824000

Python

import time
from datetime import datetime, timezone

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

# Timestamp → datetime (UTC)
dt = datetime.fromtimestamp(1741824000, tz=timezone.utc)
print(dt.isoformat())  # 2026-03-13T00:00:00+00:00

# datetime → timestamp
ts = int(datetime(2026, 3, 13, tzinfo=timezone.utc).timestamp())
print(ts)  # 1741824000

4. Implementation: Quick Conversion Helpers

// JS: Detect seconds vs milliseconds (10 vs 13 digits)
function toDate(ts) {
  const ms = ts < 1e12 ? ts * 1000 : ts;
  return new Date(ms);
}

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

// Format for display (locale-aware)
toDate(1741824000).toLocaleString('en-US', { timeZone: 'UTC' });

5. Timezone Pitfalls

6. Conclusion

Unix timestamps are the universal language of time in software. Store in UTC, handle precision carefully (seconds vs milliseconds), use timezone-aware libraries for local-time conversion, and future-proof with 64-bit integers. Use our Timestamp Converter to instantly decode any epoch value.