Unix Timestamp Guide: From Principles to Practice

Whether you are a backend developer debugging API time data or a frontend engineer handling cross-timezone date display, Unix timestamps are a format you encounter almost daily. This guide systematically covers timestamp principles, conversion methods, the 2038 problem, and practical code for obtaining and converting timestamps in major programming languages.

1. What Is a Unix Timestamp?

A Unix timestamp (Unix Epoch Time), also known as POSIX time or Epoch time, is the total number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC to a given moment. This starting point is called the "Unix Epoch."

For example, 1712697600 represents 1,712,697,600 seconds elapsed between January 1, 1970 and April 10, 2024, 00:00:00 UTC.

2. Second-Level vs Millisecond-Level Timestamps

In real-world development, you will encounter two precision levels of timestamps:

Type	Digits	Example	Common Source
Second-level	10 digits	1712697600	Python, Linux shell, MySQL
Millisecond-level	13 digits	1712697600000	JavaScript, Java, mostAPI

The easiest way to tell: if the timestamp has 10 digits, it is likely second-level; if 13 digits, it is likely millisecond-level. The conversion is: milliseconds = seconds × 1000.

3. The 2038 Problem: A Ticking Time Bomb

The scope of impact is far wider than you might think:

Affected systems: Embedded devices, older 32-bit Linux kernels, legacy database systems, C/C++ programs, and some IoT devices. Many systems running on 32-bit hardware — from traffic lights to medical devices — could be affected.

Unaffected systems: 64-bit operating systems (timestamps can represent up to 29.2 billion years), upgraded 64-bit Linux kernels, and modern programming languages (Python 3, JavaScript, etc.).

Mitigation: If your project still runs on 32-bit systems, migrate to 64-bit architecture as soon as possible. For embedded development, consider using 64-bit time variables (time64_t) instead of the traditional time_t.

4. Getting Timestamps in Major Languages

Here is code for getting the current timestamp in major programming languages — worth bookmarking:

Python

# Second-level timestamp
import time
timestamp = int(time.time())
print(timestamp)  # 1712697600

# Millisecond-level timestamp
timestamp_ms = int(time.time() * 1000)
print(timestamp_ms)  # 1712697600000

# Timestamp to date
from datetime import datetime
dt = datetime.fromtimestamp(1712697600)
print(dt)  # 2024-04-10 08:00:00 (local time) 

JavaScript

// Millisecond timestamp (JS default)
const ts = Date.now();
console.log(ts);  // 1712697600000

// Second-level timestamp
const tsSec = Math.floor(Date.now() / 1000);
console.log(tsSec);  // 1712697600

// Timestamp to date
const date = new Date(1712697600000);
console.log(date.toISOString());  // 2024-04-10T00:00:00.000Z

Java

// millisecond-level timestamps
long ts = System.currentTimeMillis();

// Second-level timestamp
long tsSec = System.currentTimeMillis() / 1000;

// Timestamp to date
import java.time.Instant;
import java.time.ZoneId;
import java.time.ZonedDateTime;
ZonedDateTime dt = Instant.ofEpochMilli(ts)
    .atZone(ZoneId.systemDefault());

Go

// Second-level timestamp
ts := time.Now().Unix()
fmt.Println(ts)

// nanosecond-level timestamps
tsNano := time.Now().UnixNano()
fmt.Println(tsNano)

// millisecond-level
tsMs := time.Now().UnixMilli()

PHP

// Second-level timestamp
$ts = time();
echo $ts;

// millisecond-level timestamps
$tsMs = round(microtime(true) * 1000);
echo $tsMs;

// Timestamp to date
echo date('Y-m-d H:i:s', $ts);

5. Common Timestamp Conversion Scenarios

Scenario 1: API returns a timestamp, frontend needs a friendly display

Most REST APIs return time fields as millisecond-level timestamps. In JavaScript, simply pass them into the Date constructor: new Date(1712697600000).toLocaleString('en-US') returns "4/10/2024, 8:00:00 AM".

Scenario 2: Database timestamps vs date format

In MySQL, the UNIX_TIMESTAMP() function converts DATETIME to a timestamp, and FROM_UNIXTIME() does the reverse. The advantage of timestamp storage is timezone independence, making it easier for cross-timezone applications.

Scenario 3: Timestamps in log analysis

Nginx logs and system logs typically use second-level timestamps. Use the command date -d @1712697600 for quick conversion.

6. Limitations of Timestamps

While timestamps are widely used in technology, there are some important caveats:

Leap seconds: Unix timestamps do not account for leap seconds. Whenever the Earth's rotation creates a 1-second deviation, UTC adds or subtracts a leap second, but Unix timestamps will either repeat or skip a second's value. This can impact high-precision timing scenarios (financial trading, scientific experiments).

Timezone-agnostic vs human-readable: Timestamps do not carry timezone information — this is their strength (unified storage) but also their weakness (not human-readable). In user-facing interfaces, always convert timestamps to a local timezone readable format.

Precision limits: Standard Unix timestamps are only precise to the second. For scenarios requiring microsecond or nanosecond precision (like high-performance trading systems), higher-precision representations are needed.

7. Online Timestamp Conversion Tools

If you only occasionally need to convert timestamps, online tools are the fastest option. Risetop's Online Timestamp Converter supports:

• Real-time second/millisecond timestamp display
• Bidirectional timestamp and readable date conversion
• Multiple timezone support
• Automatic timestamp digit detection
• Batch conversion

8. Conclusion

Unix timestamps are the most universal time representation in the computing world. Understanding their principles, the difference between second and millisecond precision, the 2038 problem, and conversion methods across languages — these are skills you will use repeatedly throughout your development career. When you encounter time-related bugs, the first step is always to check the timestamp precision and timezone settings.