Unix Timestamps Demystified: Working with Epoch Time

What is a Unix Timestamp?

A Unix timestamp (also called epoch time, POSIX time, or Unix epoch) is the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC. This moment is known as the Unix epoch and serves as the reference point for time in most computing systems.

For example, the timestamp 1700000000 represents November 14, 2023, at 10:13:20 PM UTC. The simplicity of representing time as a single number makes timestamps incredibly useful for storing, comparing, and calculating time differences in software.

Why Developers Use Timestamps

Timestamps solve several problems that human-readable dates create. They are timezone independent — a timestamp means the same moment in time regardless of where you are. They are easy to compare — just compare two numbers. They are easy to calculate with — adding 86400 to a timestamp gives you exactly one day later. And they take up very little storage space compared to date strings.

Database logs, API responses, JWT token claims, cache expiration headers, file modification times, and analytics events all commonly use Unix timestamps. If you work with any of these, you need to be comfortable converting timestamps to and from human-readable dates.

Seconds vs. Milliseconds

One of the most common sources of confusion with timestamps is the difference between seconds and milliseconds. Traditional Unix timestamps are in seconds and have 10 digits (as of 2024). JavaScript, Java, and some APIs use milliseconds, which have 13 digits.

If you see a timestamp like 1700000000, that is seconds. If you see 1700000000000, that is milliseconds. Mixing them up is a classic bug — using seconds where milliseconds are expected (or vice versa) will give you dates that are either in the 1970s or the year 55000. Always check which unit your system expects.

Timestamps Across Programming Languages

JavaScript

JavaScript uses milliseconds. Date.now() returns the current timestamp in milliseconds. To create a Date from a Unix timestamp in seconds, multiply by 1000: new Date(timestamp * 1000). To get seconds from a Date, divide by 1000: Math.floor(Date.now() / 1000).

Python

Python's time module uses seconds. time.time() returns the current Unix timestamp as a float. The datetime module can convert between timestamps and datetime objects using datetime.fromtimestamp() and datetime.timestamp().

SQL

Most SQL databases have functions for working with timestamps. PostgreSQL uses EXTRACT(EPOCH FROM timestamp) and TO_TIMESTAMP(). MySQL uses UNIX_TIMESTAMP() and FROM_UNIXTIME(). SQLite uses strftime with the %s format.

The Year 2038 Problem

Traditional 32-bit systems store Unix timestamps as signed 32-bit integers, which can represent values up to 2,147,483,647. This maximum corresponds to January 19, 2038, at 03:14:07 UTC. After this moment, 32-bit timestamps will overflow and wrap around to negative numbers, potentially causing widespread software failures.

Most modern systems use 64-bit integers for timestamps, which will not overflow for billions of years. However, legacy systems and embedded devices may still be vulnerable. This is sometimes called the Y2K38 problem.

Timezone Considerations

Unix timestamps are always in UTC. When you convert a timestamp to a human-readable date, you must decide which timezone to display it in. This is where bugs often occur — a timestamp might be correct, but the displayed date looks wrong because it is being shown in the wrong timezone.

Best practice: store all times as UTC timestamps, and only convert to local time for display purposes. This avoids issues with daylight saving time changes, timezone differences between servers and clients, and ambiguous local times.

Debugging Timestamp Issues

When timestamps seem wrong, check these common issues: Are you mixing seconds and milliseconds? Are you assuming local time when the timestamp is UTC (or vice versa)? Is daylight saving time causing an unexpected hour offset? Are you comparing timestamps from systems using different clock sources?