GizmoBench guides

Epoch Time: Ready to Paste Code for Terminal, JavaScript, and Python

GizmoBench · Updated October 17, 2026

Unix epoch time is the count of seconds since 1970-01-01 00:00:00 UTC, so a value of 0 maps to 1970-01-01T00:00:00Z. Systems store it in seconds or milliseconds, and mixing the two is the most common reason conversions fail. Detect the unit first, then convert. The rest of this guide shows how, with copy-paste examples.

TL;DR:

Python’s time.gmtime() formats seconds in UTC, while mktime() interprets input as local time; use calendar.timegm() to convert UTC structures back to epoch seconds.

An epoch identifies one instant, but formatting applies timezone and daylight saving rules; include Z or an explicit offset in logs shared across regions.

Some older 32 bit systems can overflow near 2038; use 64 bit timestamp fields in new schemas and reject values outside supported ranges.

GizmoBench

Check Timestamps in Your Browser

Use GizmoBench’s browser-based collection of practical tools to check data and complete everyday technical tasks without installing software.

Explore online tools

Where does the 1970 epoch come from?
How do seconds, milliseconds, and microseconds differ?
How do you convert epoch time on the command line, in JavaScript, and in Python?
Why does the same epoch show different clock times?
What is the 2038 problem?
Which quick checks prevent epoch mistakes?
Check your timestamps in the browser
FAQ
Sources

Where does the 1970 epoch come from?

The Unix epoch is defined as the number of seconds elapsed since 00:00:00 UTC on 1 January 1970. The date itself was a practical choice by early Unix designers: a recent, round starting point that kept early timestamps small. Nothing astronomical makes 1970 special, and that arbitrariness is the point. Everyone just has to agree on one zero.

The conventions that make the counter predictable:

Time is a single integer that grows by one each second.
POSIX-compliant Unix time excludes leap seconds and treats every day as exactly 86,400 seconds, so the number never steps backward.
Epoch time is a counter, not a clock reading, so it carries no timezone of its own.
Negative values represent instants before 1970 on systems that support them. A value of -86400, for example, is one day before the epoch, 1969-12-31T00:00:00Z.
Some platforms restrict the supported range, so a negative or very large value can behave differently depending on the runtime.

Treat the epoch as a shared reference point and the rest of the format falls into place.

How do seconds, milliseconds, and microseconds differ?

The same instant can be written at several precisions, and the digit count gives it away. Today’s timestamps look like this:

Seconds: a shorter integer, for example a timestamp representing a recent date.
Milliseconds: a larger integer than the equivalent seconds value.
Microseconds or nanoseconds: larger integer values used by some databases, tracing systems, and low-level APIs.

To detect the unit, count the digits, then sanity-check by converting. If a value read as milliseconds lands near the epoch, you may actually have seconds. If a value read as seconds lands far in the future, you may have milliseconds.

Runtimes differ by convention. In JavaScript, Date objects and Date.now() work in milliseconds since 1970-01-01T00:00:00 UTC, while many server-side APIs and command-line tools return seconds. Passing one into the other without scaling by 1000 is the classic bug.

Date.now() returns an integer count of milliseconds since the epoch, so its values are larger than typical Unix timestamps in seconds.

How do you convert epoch time on the command line, in JavaScript, and in Python?

Each snippet below is ready to paste. The GNU date command comes first, then the two languages.

GNU/Linux date, seconds to ISO: date -u -d @<seconds> +%Y-%m-%dT%H:%M:%SZ prints the corresponding UTC date. For milliseconds, divide by 1000 first. On macOS and BSD, use the platform’s documented alternative syntax.
Current epoch from the shell: date +%s returns seconds since the epoch, which is handy for checking your own conversions against a live value.
JavaScript, now and back: Date.now() gives milliseconds. Pass a millisecond timestamp to new Date(ms).toISOString(). If you hold seconds, multiply by 1000 first: new Date(seconds * 1000).
JavaScript, date to epoch: Date.parse(isoDate) returns a millisecond value, so divide by 1000 when a system wants seconds.
Python, seconds to a UTC struct: time.gmtime(seconds) returns a struct_time in UTC, and time.localtime(seconds) returns the same instant in local time. The time module documentation lists both, along with mktime().
Python, UTC struct back to epoch: calendar.timegm(time.gmtime(seconds)) converts a UTC struct back to epoch seconds. Prefer timegm() over mktime() for UTC values, because mktime() interprets its input as local time.
Python, now: time.time() returns the current epoch as a float of seconds.

Pro Tip: Test every converter with the epoch value, which must give 1970-01-01T00:00:00Z, and a current value from date +%s. If both look right, your units are right.

Why does the same epoch show different clock times?

An epoch value encodes one instant in UTC. Local time appears only when a runtime formats that instant using timezone and daylight saving rules. That separation explains most “the time is off by a few hours” reports: the stored number was fine, and the display step applied the wrong zone.

Consider an epoch value. It represents one instant in UTC. Formatting that instant for viewers in different time zones produces different local clock readings. Three different clock readings, one identical instant. A world clock makes this easy to see side by side.

Leap seconds add a second wrinkle:

POSIX Unix time leaves leap seconds out of the count, as the Python documentation also notes for POSIX systems.
The counter therefore increases monotonically, which keeps date arithmetic simple: a day is always 86,400 seconds.
The tradeoff is that Unix time does not track astronomical time exactly, so two systems may handle the leap second boundary differently.
For most application code, duration math stays correct. Only high-precision synchronization work needs to care.

What is the 2038 problem?

Some 32-bit implementations have a limited range for epoch seconds and may overflow, a problem commonly associated with 2038. The Unix Tutorial describes this as the 2038 problem for 32-bit implementations.

Some 32-bit implementations may overflow around the 2038 problem, so check the timestamp range supported by the system.

Historically, affected systems include older embedded devices, legacy file formats, and databases with 32-bit timestamp columns. Modern 64-bit time representations avoid the problem for billions of years. Practical mitigation looks like this:

Prefer 64-bit timestamps in new schemas, APIs, and file formats.
Update operating systems and runtimes that still ship 32-bit time types.
Validate ranges when parsing, so an out-of-range value is rejected instead of silently misinterpreted.

Which quick checks prevent epoch mistakes?

Most epoch bugs are unit or timezone bugs, and a short routine catches nearly all of them:

Check the scale. Smaller values may be seconds, while larger values may be milliseconds, microseconds, or nanoseconds.
Convert it twice. Decode the value as seconds and as milliseconds. The result that matches the expected date is the more likely unit.
Try the 1000 swap. If the date looks wrong, multiply or divide by 1000 and look again before touching any other code.

A sound workflow keeps things boring. Store the UTC epoch, use 64-bit milliseconds or nanoseconds when you need finer resolution, and apply the timezone only at display time. When you need to measure the gap between two stored values, a time calculator handles the hours, minutes, and seconds arithmetic.

Pro Tip: When logs will be read across regions, export ISO 8601 strings with a Z or an explicit offset alongside the raw epoch, so readers can identify the time zone.

Check your timestamps in the browser

Our Epoch Converter lets you paste any of the values from this guide and see the result immediately. It runs in your browser, so nothing is uploaded and no account is needed. It provides a quick way to check epoch values.

If you build with timestamps often, our developer tools page collects related utilities such as the JSON Formatter and Base64 Encoder & Decoder.

FAQ

What does epoch time stand for?

Epoch time is the number of seconds that have passed since a fixed starting point, the Unix epoch of 1970-01-01 00:00:00 UTC. The word “epoch” simply means that reference moment. As the Unix Tutorial puts it, it is a counter of seconds, not a timezone-specific value.

Is epoch time always UTC?

The epoch itself is defined in UTC, and the stored number identifies one instant independent of any timezone. Local time only appears when software formats that number for display. Two people in different cities decoding the same value see different clock times for the same moment.

How do I calculate epoch time?

Count the seconds between 1970-01-01 00:00:00 UTC and your target moment, ignoring leap seconds. In practice, you let a tool do it: date +%s in a shell, Date.now() in JavaScript (which returns milliseconds), or time.time() in Python.

How do I convert epoch to a human-readable date?

First confirm the unit by counting digits, then pass the value to a formatter: date -u -d @<seconds> on GNU/Linux, new Date(ms).toISOString() in JavaScript, or time.gmtime(seconds) in Python. The MDN Date reference covers the JavaScript methods in detail.