Unix Epoch Timestamp Guide for DevOps: Conversions, Commands, and Pitfalls

Originally published on 2012-02-22; fully revised and updated.

Unix timestamps show up everywhere in DevOps: logs, metrics, CI/CD events, audit records, and API payloads. This guide explains what epoch time is, how to convert it correctly across common tools, and what to watch for when timezone or unit mistakes can break debugging and automation.

What Unix epoch time means

A Unix timestamp (also called Unix time or POSIX time) is the number of seconds elapsed since 1970-01-01T00:00:00Z (UTC), not counting leap seconds. The moment 1970-01-01T00:00:00Z is epoch 0.

• Epoch time is timezone-independent as a number.
• Display formatting is timezone-dependent.
• Many systems still store or exchange timestamps as integer seconds.

Time-unit reference for quick estimates

How epoch conversion works

In practice, conversion errors usually come from timezone assumptions or unit confusion (seconds vs milliseconds). A consistent flow helps avoid both.

flowchart TD
    A[Input value] --> B{Type of input}
    B -->|Human date| C[Choose timezone]
    C --> D[Convert to epoch seconds]
    B -->|Epoch number| E[Check unit]
    E -->|Seconds| F[Format as date time]
    E -->|Milliseconds| G[Divide by 1000]
    G --> F
    D --> H[Store compare or transmit]
    F --> H

Get the current Unix timestamp

These are common one-liners used in operations scripts and troubleshooting sessions.

# Shell
date +%s

# UTC shell output (same epoch value, explicit display intent)
date -u +%sCode language: PHP (php)

import time
print(int(time.time()))Code language: JavaScript (javascript)

console.log(Math.floor(Date.now() / 1000));Code language: JavaScript (javascript)

Convert human-readable date and time to epoch

Always decide timezone first. If the input string does not include an offset, tools may assume local timezone or session timezone.

# GNU date example
date -d "2024-01-01 00:00:00 UTC" +%s

# macOS BSD date example
date -j -u -f "%Y-%m-%d %H:%M:%S" "2024-01-01 00:00:00" +%sCode language: PHP (php)

from datetime import datetime, timezone
print(int(datetime(2024, 1, 1, 0, 0, 0, tzinfo=timezone.utc).timestamp()))Code language: JavaScript (javascript)

-- PostgreSQL
SELECT EXTRACT(EPOCH FROM TIMESTAMPTZ '2024-01-01 00:00:00+00');

-- MySQL
SELECT UNIX_TIMESTAMP('2024-01-01 00:00:00');Code language: JavaScript (javascript)

Convert epoch to human-readable date and time

When converting back, choose whether you want UTC output or local timezone output for operators and dashboards.

# GNU date
date -u -d @1704067200 "+%Y-%m-%d %H:%M:%S UTC"

# macOS BSD date
date -u -r 1704067200 "+%Y-%m-%d %H:%M:%S UTC"Code language: PHP (php)

from datetime import datetime, timezone
print(datetime.fromtimestamp(1704067200, tz=timezone.utc).isoformat())Code language: JavaScript (javascript)

console.log(new Date(1704067200 * 1000).toISOString());Code language: JavaScript (javascript)

Seconds vs milliseconds: quick comparison

If an epoch value looks too large, confirm unit before parsing. A millisecond value treated as seconds usually produces dates far in the future.

Y2038 and integer-size considerations

Systems that store epoch seconds in a signed 32-bit integer can overflow in January 2038 (the Y2038 issue). Modern platforms commonly use wider integer types, but old schemas, legacy binaries, and embedded systems should still be reviewed.

Reference and original links

Original article: How to Understand Epoch and Unix Timestamp

• Epoch Converter
• MySQL epoch conversion notes
• PHP mktime reference

Common pitfalls and best practices

• Store canonical timestamps in UTC-based epoch seconds or milliseconds, then format for users at the edge.
• Document timestamp unit in every API and schema field name where possible.
• When parsing date strings, include timezone offsets explicitly instead of relying on defaults.
• In SQL, verify session and server timezone settings before comparing epoch and datetime fields.
• For cross-platform shell scripts, account for GNU date and BSD date option differences.

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.