You’ll learn exactly how Unix epoch time and UTC fit together, where common bugs arise, and the practical code/CLI/SQL you need to convert, debug, and standardize timestamps.

Featured Snippet: What is Unix Epoch Time?

Unix epoch time is a single number representing the total seconds that have elapsed since 1970-01-01 00:00:00 UTC, not counting leap seconds. It’s time-zone agnostic, sortable, and ideal for computers.

Example values:

• Epoch (seconds): 1712318400
• Epoch (milliseconds): 1712318400000
• ISO 8601 (UTC): 2026-06-21T12:34:56Z

Why engineers use it:

• Compact, language-agnostic, and easy to compare (larger = later)
• Great for database keys, logs, queues, idempotency keys, cache busting, and telemetry

Terminology note: POSIX/Unix time defines every day as exactly 86,400 seconds. Leap seconds are ignored here to keep math simple.

UTC vs GMT vs Time Zones (And Why UTC Wins in Code)

• UTC (Coordinated Universal Time): The global civil time standard. No DST, stable offset (effectively +00:00).
• GMT (Greenwich Mean Time): Historically significant; in most programming contexts treat as equivalent to UTC. Prefer “UTC” in code/docs.
• Local time zones: Defined by the IANA tz database. They can change due to DST and politics.

Always use UTC for storage, logging, and comparisons:

• Consistency across services and regions
• No DST pitfalls (“fall back” duplicates, “spring forward” gaps)
• Easier interoperability for data exchange

Convert to the user’s local time only at the edges: UI, reports, or final presentation, based on explicit settings.

Units at a Glance

• Seconds: 10 digits (e.g., 1712318400)
• Milliseconds: 13 digits (e.g., 1712318400000)
• Microseconds: ~16 digits (e.g., 1712318400000000)
• Nanoseconds: ~19 digits (e.g., 1712318400000000000)

Sanity checks:

• Seeing 1970? You probably passed seconds to a function that expected milliseconds.
• Seeing a far-future year (e.g., 51390)? You probably passed milliseconds where seconds were expected.

Type-safety tip: Prefer strong types (Java Instant/Duration, Go time.Time, .NET DateTimeOffset). If you must use integers, encode the unit in the variable name: created_at_sec, created_at_ms.

Conversion Cheat Sheet

• Seconds → milliseconds: ms = sec × 1000
• Milliseconds → seconds: sec = floor(ms / 1000)
• Epoch seconds → ISO 8601 UTC: format as YYYY-MM-DDTHH:MM:SSZ
• ISO 8601 UTC → epoch seconds: parse in UTC, then convert to integer seconds since epoch

CLI helpers:

• GNU date (Linux):
  • Epoch→ISO: date -u -d @1712318400 +%Y-%m-%dT%H:%M:%SZ
  • ISO→Epoch: date -u -d "2026-06-21T12:34:56Z" +%s
• BSD/macOS:
  • Epoch→ISO: date -u -r 1712318400 +%Y-%m-%dT%H:%M:%SZ
  • ISO→Epoch: date -u -j -f %Y-%m-%dT%H:%M:%SZ 2026-06-21T12:34:56Z +%s

Windows PowerShell:

• Epoch→ISO: [DateTimeOffset]::FromUnixTimeSeconds(1712318400).UtcDateTime.ToString("o")
• ISO→Epoch: ([DateTimeOffset]::Parse("2026-06-21T12:34:56Z")).ToUnixTimeSeconds()

Copy‑Paste Code Examples

JavaScript / TypeScript (Node/Browser)

// Now
const nowMs = Date.now();                // milliseconds since epoch
const nowSec = Math.floor(nowMs / 1000); // seconds

// Epoch (seconds) → Date
function fromSecondsToDate(sec) {
  return new Date(sec * 1000); // JS Date uses ms
}

// Date → Epoch (seconds)
function toEpochSeconds(date) {
  return Math.floor(date.getTime() / 1000);
}

// Format UTC ISO 8601 (always ends with 'Z')
function toIsoUtc(date) {
  return date.toISOString();
}

// High‑precision durations (monotonic, not wall clock)
const start = globalThis.performance?.now?.() ?? 0; // Node 18+/browser
// ... work ...
const elapsedMs = (globalThis.performance?.now?.() ?? 0) - start;

// Node.js nanosecond duration
const t0 = process.hrtime.bigint();
// ... work ...
const elapsedNs = process.hrtime.bigint() - t0;

Python 3

import datetime, time

# Now
now_sec = int(time.time())           # seconds (int)
now_ms = int(time.time() * 1000)     # milliseconds (int)

# Epoch (seconds) → UTC datetime
utc_dt = datetime.datetime.utcfromtimestamp(now_sec).replace(tzinfo=datetime.timezone.utc)

# UTC datetime → Epoch (seconds)
epoch_sec = int(utc_dt.timestamp())

# ISO 8601 UTC
iso_utc = utc_dt.isoformat().replace('+00:00', 'Z')

# Monotonic duration (not wall clock)
start = time.monotonic_ns()
# ... work ...
elapsed_ns = time.monotonic_ns() - start

PHP

// Now
$nowSec = time();                               // seconds
$nowMs  = (int) (microtime(true) * 1000);       // milliseconds

// Epoch (seconds) → DateTime (UTC)
$dt = (new DateTime('@' . $nowSec))->setTimezone(new DateTimeZone('UTC'));

// DateTime (UTC) → Epoch (seconds)
$epochSec = $dt->getTimestamp();

// ISO 8601 UTC
$isoUtc = $dt->format('Y-m-d\TH:i:s\Z'); // ensure 'Z'

Java (java.time)

import java.time.*;

// Now
Instant now = Instant.now();         // nanosecond precision
long nowSec = now.getEpochSecond();  // seconds
long nowMs  = now.toEpochMilli();    // milliseconds

// Epoch (seconds) → Instant
Instant fromSec = Instant.ofEpochSecond(1712318400L);

// ISO 8601 UTC
String isoUtc = now.toString(); // e.g., 2026-06-21T12:34:56Z

// Monotonic duration (interval measurement)
long t0 = System.nanoTime();
// ... work ...
long elapsedNs = System.nanoTime() - t0;

Go

package main
import (
    "fmt"
    "time"
)

func main() {
    now := time.Now().UTC()
    sec := now.Unix()              // seconds
    ms  := now.UnixMilli()         // milliseconds
    iso := now.Format(time.RFC3339) // ISO 8601 UTC

    // Epoch (seconds) → time.Time
    t := time.Unix(1712318400, 0).UTC()

    // Monotonic durations
    start := time.Now()
    // ... work ...
    elapsed := time.Since(start)

    fmt.Println(sec, ms, iso, t, elapsed)
}

C# (.NET)

using System;

// Now
long nowSec = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
long nowMs  = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds();

// Epoch (seconds) → DateTimeOffset (UTC)
var dto = DateTimeOffset.FromUnixTimeSeconds(1712318400);
string iso = dto.UtcDateTime.ToString("o"); // ISO 8601 with 'Z'

Rust

use std::time::{SystemTime, UNIX_EPOCH, Duration};

fn main() {
    // Now
    let now = SystemTime::now();
    let since_epoch = now.duration_since(UNIX_EPOCH).unwrap();
    let sec = since_epoch.as_secs() as i64;         // seconds
    let ms  = since_epoch.as_millis() as i128;      // milliseconds
    let ns  = since_epoch.as_nanos() as i128;       // nanoseconds

    println!("sec={} ms={} ns={}", sec, ms, ns);

    // Epoch (seconds) → SystemTime
    let t = UNIX_EPOCH + Duration::from_secs(1_712_318_400);

    // ISO 8601 formatting (use `chrono` crate in Cargo.toml)
    // chrono = { version = "0.4", features = ["clock"] }
    let dt_utc: chrono::DateTime<chrono::Utc> = t.into();
    println!("{}", dt_utc.to_rfc3339()); // e.g., 2026-06-21T12:34:56+00:00
}

Bash / Shell One-Liners

# Current epoch seconds
printf '%s\n' "$(date -u +%s)"

# Epoch (seconds) → ISO 8601 UTC (GNU date)
date -u -d @1712318400 +%Y-%m-%dT%H:%M:%SZ

# ISO 8601 UTC → epoch seconds (GNU date)
date -u -d "2026-06-21T12:34:56Z" +%s

SQL (PostgreSQL, MySQL/MariaDB, SQLite, BigQuery, Snowflake)

PostgreSQL:

-- Now (UTC) as epoch seconds
SELECT EXTRACT(EPOCH FROM NOW() AT TIME ZONE 'UTC')::bigint AS now_sec;

-- Epoch seconds → timestamptz (UTC)
SELECT to_timestamp(1712318400) AT TIME ZONE 'UTC';

-- timestamptz → epoch seconds
SELECT EXTRACT(EPOCH FROM TIMESTAMPTZ '2026-06-21 12:34:56+00')::bigint;

-- Best practice: use timestamptz for wall-clock instants; it stores UTC internally

MySQL/MariaDB:

-- Now as epoch seconds
SELECT UNIX_TIMESTAMP();

-- Epoch seconds → datetime (assumed UTC for display)
SELECT FROM_UNIXTIME(1712318400);

-- Milliseconds → datetime
SELECT FROM_UNIXTIME(1712318400000 / 1000);

SQLite:

-- Now as epoch seconds
SELECT CAST(strftime('%s','now') AS integer);

-- Epoch seconds → ISO 8601 UTC
SELECT strftime('%Y-%m-%dT%H:%M:%SZ', 'unixepoch', 1712318400);

-- ISO 8601 → epoch seconds
SELECT strftime('%s', '2026-06-21T12:34:56Z');

BigQuery:

-- Epoch seconds → TIMESTAMP (UTC)
SELECT TIMESTAMP_SECONDS(1712318400);

-- Epoch milliseconds → TIMESTAMP
SELECT TIMESTAMP_MILLIS(1712318400000);

-- TIMESTAMP → epoch seconds
SELECT UNIX_SECONDS(TIMESTAMP '2026-06-21 12:34:56+00');

Snowflake:

-- Epoch seconds → TIMESTAMP_NTZ
SELECT TO_TIMESTAMP(1712318400);

-- Epoch milliseconds → TIMESTAMP_NTZ
SELECT TO_TIMESTAMP(1712318400000, 3);

-- TIMESTAMP → epoch seconds
SELECT DATE_PART(EPOCH_SECOND, TO_TIMESTAMP('2026-06-21 12:34:56'));

MongoDB:

• BSON Date stores milliseconds since epoch in UTC.
• In aggregations, $toDate and $toLong convert between ISO dates and epoch millis.

Elasticsearch/OpenSearch:

• Many mappings support epoch_millis format.
• Example ingest: { "@timestamp": 1712318400000 } with mapping date + format: epoch_millis.

ISO 8601 and RFC 3339 in Practice

• RFC 3339 is a widely used profile of ISO 8601 for internet timestamps.
• Prefer the Z suffix to indicate UTC: 2026-06-21T12:34:56Z.
• Always include leading zeros and use 24-hour time. Avoid locale-specific formats.
• If you must include fractional seconds, keep them short and consistent (e.g., up to 3 ms or 6 µs): 2026-06-21T12:34:56.123Z.

Parsing tips:

• Always set the parsing timezone to UTC unless the string carries an offset.
• Reject ambiguous or incomplete strings (e.g., missing timezone) in APIs.

Leap Seconds, NTP Smearing, and Why You Rarely Need to Care

• Leap seconds are occasional one-second insertions to align civil time with Earth’s rotation.
• Unix/POSIX time omits leap seconds; it assumes every day is exactly 86,400 seconds.
• NTP servers often “smear” a leap second gradually (e.g., over 24 hours) so clocks remain monotonic and applications stay happy.

Impact for developers:

• Most app-level code never sees a distinct 23:59:60.
• Don’t schedule mission-critical events at the exact leap second boundaries; use tolerant windows and idempotency.
• If you operate time-sensitive infra, know your NTP mode (step vs smear). Popular vendors like Google Cloud and AWS provide leap smearing; chrony can be configured with leapsecmode smear.

DST and Local Time Pitfalls (Never Compare Local Times)

• Spring forward: One-hour gap of local time; some local times never occur.
• Fall back: One-hour repeat; some local times occur twice.
• Comparing or scheduling by local times creates off-by-one-hour bugs in March/October/November.

Strategy:

• Store and compare in UTC epoch or UTC timestamps.
• Convert to local time only at presentation time.
• For recurring schedules tied to local law (e.g., “every day at 8 a.m. Los Angeles”), use a time-zone-aware scheduler (cron with TZ, or libraries that use IANA tz data) and record the canonical tz ID.

Year 2038 Problem (Y2038) and Embedded Systems

• Systems using a signed 32-bit time_t (seconds since epoch) overflow on 2038-01-19 03:14:07 UTC.
• Modern 64-bit OSes and libraries use 64-bit time; most servers are safe. Embedded/legacy 32-bit devices may not be.

Readiness checklist:

• Use 64-bit types for epoch seconds (BIGINT in SQL, long in Java/C#, i64 in Rust).
• Verify container base images and toolchains on 64-bit.
• Audit SDKs for 32-bit epoch use on mobile/IoT.

Security Considerations: Tokens, Signatures, and Logs

• JWT exp/nbf/iat are NumericDate values: epoch seconds.
• Verify token lifetimes in UTC and account for small clock skew (e.g., 60–120 seconds).
• Log authentication events with UTC timestamps and include both ISO 8601 and epoch for greppability.

Quick JWT decode (no verification, for debugging only):

echo 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....' | cut -d '.' -f2 | base64 -d | jq

Data Engineering: Event Time vs Processing Time

• Event time: when the event actually occurred (from the device/source), usually epoch seconds/ms in UTC.
• Processing time: when your system ingested the event.
• Keep both. Use event time for analytics and watermarks; processing time for ops/debugging.
• Late data: handle with watermarks and window grace periods.

Logging and Observability

Best practices:

• Use ISO 8601 UTC with Z and include epoch for exactness: ts_iso, ts_epoch_ms.
• Ensure log agents do not double-convert timestamps (avoid accidental local time parsing).
• In Elasticsearch/OpenSearch, store @timestamp as UTC and specify format.
• In Prometheus, timestamps are seconds with fractional precision; let Prom scrape time, avoid manual stamping unless necessary.

Anti‑Patterns to Avoid

• Storing local time without timezone context.
• Mixing seconds and milliseconds in the same field name.
• Comparing wall-clock times to measure durations.
• Truncating by string slicing instead of proper parsing.
• Relying on system locale-dependent date formats in APIs.

Production Checklist (Copy/Paste)

• All services use NTP/chrony with consistent configuration (prefer smear in large fleets).
• Store timestamps in UTC (epoch seconds or ISO 8601 with Z).
• If integers are stored, include unit in the column/field name.
• In SQL: prefer timestamptz (Postgres) or TIMESTAMP (UTC) semantics; document assumptions.
• Validate inbound timestamps strictly; reject ambiguous formats.
• Use monotonic clocks for performance measurements and timeouts.
• Include both human-readable (ISO 8601) and machine-readable (epoch ms) in logs/events where feasible.
• Test around DST transitions and month/year boundaries.
• Document SLA/TTL units explicitly (seconds vs milliseconds) in API specs.

Troubleshooting Matrix: Symptoms → Likely Root Cause

• “All dates show 1970-01-01” → Seconds passed to a milliseconds-based API (e.g., JS Date expects ms).
• “Dates are in year 51390” → Milliseconds passed where seconds are expected.
• “Job fired one hour early/late” → Local time or DST used internally; store/compare in UTC.
• “Token expired unexpectedly” → Clock skew between services; add allowable drift and ensure NTP sync.
• “Graph gaps at odd times” → Time parsing failed (timezone mismatch) or logs in mixed formats.

Naming, Types, and Storage Design

• Choose one canonical storage format per system boundary. Recommended:
  • APIs: ISO 8601 UTC (RFC 3339) or epoch milliseconds with clear field names.
  • Databases: Postgres timestamptz for instants; Bigint for raw epochs when performance/size demands it.
• Indexing/Partitioning:
  • Partition time-series tables by day/month (UTC) to simplify rollups and retention.
  • Use covering indexes on time columns for range scans.

Example Postgres schema:

CREATE TABLE events (
  id               bigserial PRIMARY KEY,
  event_time       timestamptz NOT NULL,  -- stored as UTC
  event_time_ms    bigint GENERATED ALWAYS AS (EXTRACT(EPOCH FROM event_time) * 1000)::bigint STORED,
  payload          jsonb NOT NULL
);
CREATE INDEX ON events (event_time);
CREATE INDEX ON events (event_time_ms);

Scheduling and Cron with Time Zones

• Prefer UTC for cron entries to avoid DST surprises.
• If you must run “8 a.m. local time,” run a time-zone-aware scheduler or container with TZ set and test both DST transitions yearly.

Example:

# crontab (UTC recommended)
# Run at 00:00 UTC daily
0 0 * * * /usr/local/bin/job.sh

CLI Power Moves for Everyday Debugging

• Convert mixed JSON epochs with jq:

echo '{"ts_ms":1712318400000}' | jq '.ts_ms_iso = (.ts_ms / 1000 | todateiso8601)'

• Verify system clock and NTP:

chronyc tracking  # or: timedatectl status; ntpq -p

• Quick Python one-liners:

python3 - <<'PY'
import datetime, time
sec = int(time.time())
print('sec', sec)
print('iso', datetime.datetime.utcfromtimestamp(sec).replace(tzinfo=datetime.timezone.utc).isoformat().replace('+00:00','Z'))
PY

Measuring Durations Correctly (Monotonic Clocks)

• Use monotonic time sources for intervals/timeouts: they aren’t affected by NTP corrections, DST, or manual clock changes.
• Examples:
  • Java: System.nanoTime()
  • Go: time.Since(start)
  • Python: time.monotonic() / time.monotonic_ns()
  • Node: process.hrtime.bigint()

Never compute durations by subtracting wall-clock timestamps.

Internationalization and Display

• Always store UTC. Convert to the user’s tz for display using locale-aware formatting APIs.
• Show the timezone abbreviation or offset when it matters: “2026-06-21 08:34 (UTC-04:00).”
• For logs and machine interfaces, prefer UTC with Z to avoid ambiguity.

Testing Time

• Freeze time in tests for determinism:
  • Python: freezegun
  • Java: java.time.Clock with FixedClock
  • JS/TS: Jest fake timers, sinon.useFakeTimers()
  • Ruby: Timecop
• Test boundaries: DST transitions, month-end, leap day, year rollovers.

Frequently Asked Questions (FAQ)

Q: Is UTC the same as GMT?

• For modern programming, treat GMT as equivalent to UTC. Use UTC in code and docs.

Q: Do leap seconds affect Unix epoch time?

• No. POSIX time ignores leap seconds. NTP often smears the second so apps don’t notice.

Q: Should APIs use ISO 8601 or epoch milliseconds?

• Either is fine if you’re consistent. ISO 8601 is human-friendly and explicit. Epoch ms is compact and fast. Document clearly and add “Z.”

Q: Why is my JavaScript date in 1970?

• You likely passed seconds to the Date constructor, which expects milliseconds.

Q: What about the 2038 problem?

• Use 64-bit epoch types. Most 64-bit systems are safe; audit embedded/legacy stacks.

Q: Should I store time zones in the database?

• Store instants in UTC. If user-specific local times matter (e.g., for scheduling), store their IANA tz ID separately.

Real‑World Patterns and Recipes

• Round to the nearest minute (UTC):

import datetime
now = datetime.datetime.now(datetime.timezone.utc)
rounded = now.replace(second=0, microsecond=0)

• Start/end of day (UTC):

function startOfDayUtc(d = new Date()) {
  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 0, 0, 0, 0));
}
function endOfDayUtc(d = new Date()) {
  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate(), 23, 59, 59, 999));
}

• Parse ISO 8601 reliably in Go:

// Handles 2026-06-21T12:34:56Z and with fractional seconds
func mustParseRFC3339(s string) time.Time {
    t, err := time.Parse(time.RFC3339Nano, s)
    if err != nil { panic(err) }
    return t.UTC()
}

• Postgres: truncate to hour/day for rollups:

SELECT date_trunc('hour', event_time) AS hour_bucket, count(*)
FROM events
GROUP BY 1
ORDER BY 1;

Validation and Safe Parsing

• Reject ambiguous formats (like “06/07/26 12:34”) in public APIs.
• Accept only:
  • ISO 8601 with Z or explicit offset (+00:00) and full date+time.
  • Epoch integers with documented units.
• On parse failure, return a clear error with the accepted format.

Performance, Scale, and Storage Size

• 64-bit epoch seconds fit in 8 bytes; milliseconds also in 8 bytes until year ~292 million.
• ISO 8601 strings are larger but self-descriptive; compress well and improve debuggability.
• For hot paths, consider storing epoch ms as BIGINT and render ISO 8601 at the edge.

Quick Field Guide: Choosing the Right Representation

• Internal compute, compactness matters: epoch milliseconds as 64-bit integer.
• Cross-system APIs and logs: ISO 8601 UTC with Z, optionally include epoch for correlation.
• Analytics/SQL: native timestamp types with UTC semantics plus indexed BIGINT for heavy range scans when needed.

Common Edge Cases and How to Handle Them

• Null or missing timestamps: never default to 1970-01-01; treat as null/invalid; return 400 or skip record.
• Timezone confusion: explicitly convert to UTC at ingestion; store a normalized field.
• Milliseconds vs seconds drift: create linters/schemers that enforce allowed units per field.
• Negative epochs (pre-1970): ensure your runtime/database supports them if needed.

Tooling: Instantly Convert and Validate

• Use the ZenixTools Epoch Converter to:
  • Convert seconds/milliseconds to ISO 8601 and back
  • Detect unit mismatches
  • Share permalinks for debugging

Link: https://www.zenixtools.com/tools/epoch-converter

Summary

Unix epoch time and UTC give you a universal, unambiguous foundation for time in distributed systems. Use UTC end-to-end, prefer ISO 8601 in public boundaries, measure durations with monotonic clocks, and document your units relentlessly. With these patterns—and a reliable converter in your toolbox—you’ll avoid the classic time traps that wake engineers at 3 a.m.

Glossary

• Epoch (Unix/POSIX): Seconds since 1970-01-01T00:00:00Z.
• UTC: Coordinated Universal Time, no DST.
• RFC 3339: Internet-friendly profile of ISO 8601.
• Leap second: Occasional extra second to sync with Earth’s rotation; not represented in POSIX time.
• Monotonic clock: Clock that never jumps backward; used for intervals.

Further Reading

• IANA Time Zone Database (tzdata)
• RFC 3339: Date and Time on the Internet
• NTP and leap smearing vendor docs (chrony/ntpd, cloud providers)

Need a fast, reliable conversion right now? Try the ZenixTools Epoch Converter: https://www.zenixtools.com/tools/epoch-converter