How to Convert an Epoch (Unix) Timestamp
A practical guide to Unix epoch timestamps — what they are, how to convert them to human-readable dates, and how to work with them in JavaScript, Python, and the command line.
What is a Unix epoch timestamp?
A Unix epoch timestamp is the number of seconds (or milliseconds) that have elapsed since 00:00:00 UTC on 1 January 1970, known as the Unix epoch. It provides a timezone-independent, language-independent way to represent a specific moment in time, which makes it the standard for logs, APIs, databases, and inter-system communication.
Seconds vs. milliseconds
Different systems use different precisions. POSIX systems and most Unix utilities use seconds; JavaScript's Date uses milliseconds; some modern APIs use microseconds or nanoseconds. Always check which unit a value is in — multiplying a millisecond value by 1000 is a common mistake.
# Seconds (10 digits, starts with 17… in 2024)
1700000000
# Milliseconds (13 digits)
1700000000000
# Microseconds (16 digits)
1700000000000000Converting in JavaScript
JavaScript's Date object takes milliseconds. Multiply a seconds-based timestamp by 1000 before passing it to new Date().
// Current timestamp (milliseconds)
const nowMs = Date.now();
// From a seconds-based Unix timestamp
const ts = 1700000000;
const date = new Date(ts * 1000);
console.log(date.toISOString()); // "2023-11-14T22:13:20.000Z"
console.log(date.toLocaleString("en-US", { timeZone: "America/New_York" }));
// Back to epoch seconds
const backToSeconds = Math.floor(date.getTime() / 1000);
console.log(backToSeconds); // 1700000000Converting in Python
Python's datetime module handles both aware (timezone-attached) and naive datetimes. Use timezone-aware datetimes to avoid bugs around local system timezone.
from datetime import datetime, timezone
ts = 1700000000
# UTC datetime
utc_dt = datetime.fromtimestamp(ts, tz=timezone.utc)
print(utc_dt.isoformat()) # 2023-11-14T22:13:20+00:00
# Current epoch timestamp
now = datetime.now(timezone.utc).timestamp()
print(int(now)) # e.g. 1700000000
# Format as a readable string
print(utc_dt.strftime("%B %d, %Y at %H:%M UTC")) # November 14, 2023 at 22:13 UTCConverting from the command line
On macOS and Linux, date can format an epoch timestamp. The flag differs by platform.
# macOS (BSD date)
date -r 1700000000
# Tue Nov 14 22:13:20 UTC 2023
# Linux (GNU date)
date -d @1700000000
# Tue Nov 14 22:13:20 UTC 2023
# Get current epoch
date +%sThe year 2038 problem
Systems that store timestamps as 32-bit signed integers will overflow on 19 January 2038 at 03:14:07 UTC — this is the Unix Y2K38 problem. Modern 64-bit systems are not affected, but embedded systems and legacy databases using INT(11) columns may still be at risk.
How do I know if a timestamp is in seconds or milliseconds?
Count the digits. A 10-digit value starting with 17 is almost certainly seconds (year ~2023). A 13-digit value is milliseconds. If you get a date in 1970 or 50,000 years in the future, you guessed wrong — divide or multiply by 1000.
Does a Unix timestamp include timezone information?
No. A Unix timestamp is always relative to UTC (the epoch is 00:00:00 UTC on Jan 1, 1970). When you display it as a human-readable date, you choose which timezone to render it in.
What is the maximum Unix timestamp for a 32-bit integer?
2,147,483,647 seconds, which corresponds to 03:14:07 UTC on 19 January 2038. After that, a signed 32-bit integer wraps to a large negative number.
Understanding Timezones and UTC Offsets
A practical guide to timezones — understand UTC, IANA timezone names, UTC offsets, Daylight Saving Time, and how to reliably work with times across zones in code.
Read guide →Working with Dates Across Time Zones in JavaScript
A practical guide to JavaScript dates — the Date object, UTC vs local time, formatting, parsing, and how to avoid the most common time zone bugs.
Read guide →