Definition

UUID v8 is a UUID format defined in RFC 9562 §5.8 for custom or experimental UUID implementations. It sets the version nibble to 8 (four bits at position 48–51) and the variant bits to 10 (two bits at position 64–65), leaving the remaining 122 bits completely implementation-defined.

UUID v8 is effectively a “bring your own layout” slot within the UUID format. It produces valid UUID strings that pass standard format validation, while the internal structure is entirely determined by the implementing system.

Bit layout

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                        custom_a (32)                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          custom_b (16)        | ver |       custom_c (12)     |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                       custom_d (62)                       |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

ver = 1000 (8), var = 10. All custom_* fields are defined by the implementation.

When to use UUID v8

UUID v8 is appropriate when:

  1. You need a higher-resolution timestamp than UUID v7 — UUID v7 uses 48-bit millisecond precision. UUID v8 can encode a 60-bit microsecond or nanosecond timestamp for applications requiring sub-millisecond ordering.
  2. You need to embed application-specific metadata — tenant ID, datacenter ID, or a schema version in the UUID itself for routing decisions without a database lookup.
  3. You are implementing a custom ID scheme that must be UUID-format-compatible for storage in existing systems.

For the vast majority of applications, UUID v7 covers the time-ordered use case and UUID v4 covers the random use case. UUID v8 should be a last resort.

Example: nanosecond-precision UUID v8

// Custom UUID v8 with nanosecond timestamp for high-frequency trading systems
function uuidV8WithNanoseconds() {
  const nsTime = BigInt(Date.now()) * 1_000_000n; // Approximate: ms → ns
  // In production use process.hrtime.bigint() for actual ns precision

  const timeHex = nsTime.toString(16).padStart(15, '0');
  const random = crypto.getRandomValues(new Uint8Array(8));
  const randHex = Array.from(random).map(b => b.toString(16).padStart(2,'0')).join('');

  // Layout: 48 bits time (bits 0-47), 12 bits time continued (bits 52-63),
  //         62 bits random (bits 66-127)
  const a = timeHex.slice(0, 8);
  const b = timeHex.slice(8, 12);
  const c = timeHex.slice(12, 15); // 12 bits
  const variant = (parseInt(randHex.slice(0, 2), 16) & 0x3f | 0x80).toString(16).padStart(2,'0');
  const d = randHex.slice(2, 18);

  return `${a}-${b}-8${c}-${variant}${randHex.slice(4, 8)}-${d}`;
}

This encodes nanosecond timestamps in positions that preserve UUID v8’s version (8) and variant (8, 9, a, or b) bits. The uuid npm package does not provide a v8 generator — you must implement the layout yourself.

Example: tenant-scoped UUID v8

Embed a 32-bit tenant ID in the first group for sharding decisions:

import struct
import os

def uuid_v8_tenant(tenant_id: int) -> str:
    """UUID v8 with 32-bit tenant ID in the first group."""
    # 32 bits: tenant ID
    # 16 bits: random
    # 12 bits: random (after version nibble)
    # 62 bits: random (after variant)
    rand = os.urandom(10)  # 80 bits random

    a = format(tenant_id & 0xFFFFFFFF, '08x')
    b = rand[:2].hex()
    c = rand[2:4].hex()[:3]  # 12 bits (version nibble handled separately)
    variant = format((rand[4] & 0x3f) | 0x80, '02x')
    d = rand[5:].hex()

    return f"{a}-{b}-8{c}-{variant}{rand[4:6].hex()}-{rand[4:10].hex()}"

This lets a routing layer extract the tenant ID without a database lookup:

def tenant_from_uuid_v8(uuid_v8: str) -> int:
    return int(uuid_v8.split('-')[0], 16)

UUID v8 in existing systems

Existing infrastructure that stores and indexes UUID strings treats UUID v8 identically to v4 or v7 — the 36-character string is stored, compared, and indexed without interpretation. Only your application code needs to understand the custom layout. Store UUID v8 in:

The PostgreSQL UUID type documentation confirms that all valid UUID format strings (version 1–8) are accepted without error.

External references

Frequently asked questions

What is UUID v8 and when should I use it?

UUID v8 is defined in RFC 9562 §5.8 as a format for custom UUID implementations. The version nibble is set to 8 and the variant bits to 10, but all other 122 bits are defined by the implementation. Use UUID v8 when you need a UUID-format identifier that embeds custom metadata (a tenant ID, a node ID, a higher-precision timestamp) while remaining compatible with systems that accept standard UUID format strings. Most applications should use UUID v7 for time-ordered IDs and UUID v4 for random IDs — UUID v8 is for specialised cases.

Is UUID v8 compatible with standard UUID libraries and databases?

UUID v8 values pass format validation in any library that checks the 8-4-4-4-12 hexadecimal structure, version digit (1–8), and variant bits (8, 9, a, b). The uuid npm package's validate() accepts UUID v8. PostgreSQL's uuid column type stores UUID v8 as 16 bytes without modification. The internal layout is not interpreted by standard libraries — only your application code knows how to decode the custom bits.

How does UUID v8 differ from UUID v7?

UUID v7 has a defined bit layout: 48-bit Unix millisecond timestamp, 4-bit version, 12-bit rand_a (counter or random), 2-bit variant, 62-bit rand_b. The layout is specified by RFC 9562 §5.7 and implemented identically by all compliant libraries. UUID v8 has no defined layout beyond version and variant bits — two UUID v8 implementations from different vendors are completely incompatible at the bit level. UUID v7 is the standard choice for time-ordered IDs; UUID v8 is for custom encoding needs.