Definition
The UUID epoch is the reference timestamp from which time-based UUIDs count their time offset. Different UUID versions use different epochs:
| UUID Version | Epoch | Unit | Bits |
|---|---|---|---|
| v1 | October 15, 1582 (Gregorian calendar start) | 100 nanoseconds | 60 |
| v6 | October 15, 1582 (Gregorian calendar start) | 100 nanoseconds | 60 |
| v7 | January 1, 1970 (Unix epoch) | 1 millisecond | 48 |
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:
- UUID v7 with Unix milliseconds → direct comparison with
Date.now(),time.time(), Kafka offsets, log timestamps - UUID v1 with Gregorian 100-ns ticks → requires a fixed offset subtraction and unit conversion before comparison
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.
Related terms
- Time-Based UUID — v1, v6, and v7 compared
- Time Precision — 100-nanosecond vs millisecond resolution
- Clock Sequence — the UUID v1 field that handles clock resets
- Monotonic Counter — UUID v7 within-ms ordering
External references
- RFC 9562 §5.1 — UUID v1 timestamp
- RFC 9562 §5.7 — UUID v7 timestamp
- PostgreSQL 18 — uuid_extract_timestamp()
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.