The year is 1970. January 1st. Midnight UTC. Somewhere in Bell Labs, a team of engineers decided that this moment would be the anchor point for all computer time — "The Epoch." Every moment since then can be represented as a simple integer: the number of seconds (or milliseconds) elapsed since that moment.
This is the Unix timestamp, and it remains one of the most elegant engineering decisions in computing. This guide explains everything you need to know to work with timestamps confidently.
What is a Unix Timestamp?
A Unix timestamp (also called POSIX time or Epoch time) represents a point in time as the number of seconds that have elapsed since the Unix Epoch: January 1, 1970, 00:00:00 UTC.
For example:
- 0 = January 1, 1970, 00:00:00 UTC
- 1000000000 = September 9, 2001, 01:46:40 UTC
- 1715000000 = approximately May 6, 2024
The timestamp for a future time (say, year 2100) is simply a larger positive integer. Times before the epoch are negative numbers.
Current Unix time (at publication): approximately 1,745,000,000
Seconds vs Milliseconds: The Source of Endless Bugs
This is the single most common source of timestamp bugs in production systems.
Unix traditionally uses seconds: Date.now() / 1000 in JavaScript, time.time() in Python, System.currentTimeMillis() / 1000 in Java.
JavaScript's Date object uses milliseconds: Date.now() returns milliseconds since the epoch. So the current time in JavaScript is a 13-digit number like 1715234567890, not the 10-digit 1715234567.
Spotting which unit you have:
- 10 digits → seconds (e.g., 1715234567) — valid until year 2286
- 13 digits → milliseconds (e.g., 1715234567890)
- 16 digits → microseconds
Common bug: Passing a millisecond timestamp to a function expecting seconds results in a date billions of years in the future. Always check the magnitude of timestamps when debugging.
Timezone Handling: The Other Trap
Unix timestamps are always in UTC — they have no timezone. The number 1715234567 represents the same moment in time everywhere on Earth. What changes is how humans display it.
When you convert a timestamp to a human-readable date:
- The timestamp 1715234567 is 2024-05-09 09:22:47 UTC
- In New York (UTC-4): 2024-05-09 05:22:47
- In Tokyo (UTC+9): 2024-05-09 18:22:47
Best practices:
1. Store timestamps in UTC in your database — never store local time
2. Convert to local time only for display
3. Use an IANA timezone identifier (e.g., America/New_York) rather than a raw offset (e.g., -4:00) to handle daylight saving time correctly
4. Libraries like Temporal (new JS API), date-fns-tz, and Luxon handle timezone conversions reliably
Getting the Current Timestamp
In different languages:
// JavaScript — milliseconds
Date.now() // 1715234567890
Math.floor(Date.now() / 1000) // 1715234567 — seconds
// Using Temporal (modern API)
Temporal.Now.instant().epochSeconds // 1715234567# Python
import time
int(time.time()) # 1715234567
import datetime
datetime.datetime.utcnow().timestamp() # 1715234567.123# Shell
date +%s # 1715234567-- SQL (varies by database)
SELECT UNIX_TIMESTAMP(); -- MySQL
SELECT EXTRACT(EPOCH FROM NOW()); -- PostgreSQLConverting Between Timestamps and Dates
Timestamp → Human-readable date:
// JavaScript
new Date(1715234567 * 1000).toISOString()
// "2024-05-09T09:22:47.000Z"
new Date(1715234567 * 1000).toLocaleString('en-US', {
timeZone: 'America/New_York'
})
// "5/9/2024, 5:22:47 AM"# Python
from datetime import datetime, timezone
datetime.fromtimestamp(1715234567, tz=timezone.utc).isoformat()
# '2024-05-09T09:22:47+00:00'Date → Timestamp:
// JavaScript
Date.parse("2024-05-09T09:22:47Z") / 1000 // 1715234567
new Date("2024-05-09T09:22:47Z").getTime() / 1000 // 1715234567# Python
from datetime import datetime, timezone
datetime(2024, 5, 9, 9, 22, 47, tzinfo=timezone.utc).timestamp()
# 1715234567.0The Y2K38 Problem
The original Unix timestamp was stored as a signed 32-bit integer, which can hold values from approximately -2.1 billion to +2.1 billion. The maximum value (2,147,483,647) corresponds to January 19, 2038, 03:14:07 UTC — after which a 32-bit signed timestamp will overflow and wrap to a large negative number (January 13, 1901).
This is analogous to the Y2K bug but for 2038.
Is this still a problem? Modern 64-bit systems use 64-bit timestamps internally, which extends the range to 292 billion years from now. However, legacy embedded systems, some databases, and 32-bit devices may still be affected.
Actions to take:
- Use 64-bit integers or equivalent (bigint in JS, int64 in Go, BIGINT in SQL) for timestamp fields
- Audit any legacy code or 32-bit microcontrollers in your infrastructure
- Choose TIMESTAMP WITH TIME ZONE (or DATETIME) in PostgreSQL over TIMESTAMP when dealing with dates far in the future
ISO 8601 vs Unix Timestamps
You'll commonly encounter two timestamp formats:
Unix timestamp: 1715234567 — a plain integer, compact, unambiguous, no timezone confusion, easy to compare and sort
ISO 8601: "2024-05-09T09:22:47Z" — human-readable, self-describing, includes timezone indicator
When to use which:
- Use Unix timestamps for storage, calculations, comparisons, and APIs — they're simpler to process and sort
- Use ISO 8601 for display, logging, exports, and user-facing fields — humans can read them without conversion
- Always include the Z suffix (UTC) or explicit offset (+00:00) in ISO 8601 strings to avoid timezone ambiguity