uuidv8 1.0.0

Generate UUID version 8 identifiers as defined in RFC 9562 — custom-use UUIDs with cryptographically random fields

uuidv8

Generate UUID version 8 identifiers as defined in RFC 9562.

f6440f3e-14a2-8293-add2-1066de13086a
         ^^^^                          ← version = 8
                   ^                  ← variant = 10xx

No dependencies. Uses only the Python standard library (secrets).

---

What is UUID v8?

UUID v8 is a custom-use UUID format introduced in RFC 9562 alongside the more widely known v7. Where v7 is opinionated (millisecond timestamp + random bits), v8 leaves 122 of its 128 bits entirely up to you.

The spec only mandates two things:

Bits	Field	Value
48–51	version	1000 (= 8)
64–65	variant	10

Everything else — the remaining 122 bits split across custom_a, custom_b, and custom_c — is yours to define.

This package fills all custom fields with cryptographically random bytes, making it a drop-in for any situation where you need a universally unique, opaque identifier and none of the earlier UUID versions quite fit.

---

When to use UUID v8

Situation	Good fit?
You need a random, unique ID with no embedded meaning	Yes — same collision resistance as v4
You want a UUID that signals "custom / vendor-specific" to readers of your schema	Yes — the 8 version nibble is a clear marker
You are building a proprietary UUID layout (e.g. embedding a shard ID or timestamp in your own format)	Yes — swap in your own bits instead of random ones
You need time-sortable IDs	No — use UUID v7
You need backwards compatibility with systems that only accept v4	No — use UUID v4

---

Installation

pip install uuidv8

Requires Python 3.8 or later. No third-party dependencies.

---

Usage

from uuidv8 import uuidv8, validate

uid = uuidv8()
print(uid)            # "f6440f3e-14a2-8293-add2-1066de13086a"
print(validate(uid))  # True

---

API

uuidv8() -> str

Returns a new UUID v8 string with cryptographically random custom fields.

uuidv8()  # "a1b2c3d4-e5f6-8abc-9def-0123456789ab"

The returned string is always lowercase and follows the standard 8-4-4-4-12 hyphenated format.

validate(uuid: object) -> bool

Returns True if the given value is a valid UUID v8 (correct format, version nibble = 8, variant bits = 10xx). Returns False for anything else, including other UUID versions.

validate("a1b2c3d4-e5f6-8abc-9def-0123456789ab")  # True  — valid v8
validate("f47ac10b-58cc-4372-a567-0e02b2c3d479")  # False — this is v4
validate("not-a-uuid")                             # False
validate(None)                                     # False

---

UUID v8 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                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|           custom_a            |  ver  |       custom_b        |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                       custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           custom_c                            |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Field	Bits	Value (this package)
custom_a	48	random
ver	4	8
custom_b	12	random
var	2	10
custom_c	62	random

---

License

GPL-3.0