Definition

The UUID epoch is the reference timestamp from which time-based UUIDs count their time offset. Different UUID versions use different epochs:

UUID VersionEpochUnitBits
v1October 15, 1582 (Gregorian calendar start)100 nanoseconds60
v6October 15, 1582 (Gregorian calendar start)100 nanoseconds60
v7January 1, 1970 (Unix epoch)1 millisecond48

See Time-Based UUID for a full comparison of v1, v6, and v7.

UUID v1 and v6 — Gregorian epoch

UUID v1 and v6 count 100-nanosecond intervals since October 15, 1582 — the date the Gregorian calendar was adopted. This epoch was chosen in the original UUID specification (RFC 4122, 2005) because the 60-bit counter starting from 1582 would not overflow until around year 5236, providing a generous practical range.

// UUID v1 timestamp — extract Gregorian ticks
function extractV1Timestamp(uuid: string): Date {
  const hex = uuid.replace(/-/g, '');
  // UUID v1 timestamp: time_low (8) + time_mid (4) + time_hi (3) — scrambled
  const timeLow  = hex.slice(0, 8);
  const timeMid  = hex.slice(8, 12);
  const timeHigh = hex.slice(13, 16);  // strip version nibble
  const ticks = BigInt('0x' + timeHigh + timeMid + timeLow);

  // Convert from Gregorian (1582) to Unix (1970) epoch
  const gregorianToUnixMs = 122192928000000000n; // 100-ns ticks between epochs
  const unixMs = (ticks - gregorianToUnixMs) / 10000n;
  return new Date(Number(unixMs));
}

The Gregorian-to-Unix offset is 12,219,292,800 seconds (1,000 years, 4 months, 15 days) — approximately 1.22 × 10¹⁷ 100-nanosecond ticks.

UUID v7 — Unix epoch

UUID v7 uses the Unix epoch (January 1, 1970 UTC) — the same reference point as Date.now(), time.time(), and every language’s standard timestamp API. The 48-bit millisecond counter overflows at 2^48 - 1 milliseconds after the epoch — approximately year 10,895, over 8,900 years in the future.

// UUID v7 timestamp — extract Unix milliseconds
function extractV7Timestamp(uuid: string): Date {
  const ms = parseInt(uuid.replace(/-/g, '').slice(0, 12), 16);
  return new Date(ms);
}

const id = '018fbe3a-4c5d-7b12-8abc-0123456789ab';
extractV7Timestamp(id);  // → exact creation time to nearest millisecond

PostgreSQL 18 provides uuid_extract_timestamp(uuid) for the same operation in SQL — no application code needed. See PGDay Paris 2026 for benchmarks using this function.

Why the epoch choice matters

The epoch determines how easy it is to compare UUID timestamps to real-world times:

For new systems, the Unix epoch and millisecond precision of UUID v7 are strictly more convenient. The precision difference (1 ms vs 100 ns) is rarely meaningful in practice because operating system clocks rarely expose sub-millisecond resolution. See Time Precision.

External references

Frequently asked questions

Why does UUID v1 use the Gregorian epoch instead of the Unix epoch?

UUID v1 was designed in the early 1990s when the Unix epoch was not yet the universal standard. The Gregorian epoch (October 15, 1582) was chosen to span from the start of the Gregorian calendar to well beyond any foreseeable future, using a 60-bit counter in 100-nanosecond ticks. UUID v7 (RFC 9562, 2024) chose the Unix epoch because it is universally understood, directly comparable to Date.now() and time.time(), and the 48-bit millisecond counter spans over 8,900 years — more than sufficient. See Time-Based UUID.

How do I extract the timestamp from a UUID v7 value?

The first 48 bits of a UUID v7 are the Unix millisecond timestamp. Extract them by taking the first 12 hex characters and parsing as a base-16 integer: parseInt(uuid.replace(/-/g, '').slice(0, 12), 16). The result is milliseconds since January 1, 1970 UTC. Convert to a Date with new Date(ms). PostgreSQL 18 provides uuid_extract_timestamp(uuid) for the same operation in SQL. See Time Precision.