What is a UUID?
A UUID (Universally Unique Identifier) is a 128-bit, or 16-byte, identifier. It helps different systems issue IDs for orders, messages, or database rows. The generation method depends on its version.
UUID overview
UUIDs can be issued without asking a central numbering server every time. The name does not mean that duplicate values are impossible.
Text representation
- The usual text form contains 32 hexadecimal digits and four hyphens: 36 characters in groups of 8-4-4-4-12.
- Uppercase and lowercase letters represent the same value. The 128-bit value and its 36-character text storage are different representations.
- RFC 9562 supersedes RFC 4122 and also defines versions 6, 7, and 8.
Example UUIDv4
The third block begins with version 4; the fourth begins with variant nibble a. This fixed value illustrates the layout.
1f593de9-8f62-4c48-a8c3-123456789abcStructure and bit layout
The following describes ordinary UUIDs in the RFC 9562 variant. Remaining fields hold time, random data, or hash data depending on the version.
The five blocks
| Block | Size | Meaning |
|---|---|---|
| 1 | 32 bit | 8 hex digits |
| 2 | 16 bit | 4 hex digits |
| 3 | 16 bit | First 4 bits identify the version |
| 4 | 16 bit | First 2 bits are variant 10 |
| 5 | 48 bit | 12 hex digits |
Read version and variant
- The version is the first digit of the third block, immediately after the second hyphen: 4 means v4, 7 means v7.
- In this variant, the fourth block starts with 8, 9, a, or b, whose two most significant bits are 10.
- Nil (all zero bits) and Max (all one bits) are special UUIDs. Accepted versions and special values depend on the API contract.
Common versions
The generation input affects time disclosure and reproducibility.
Four common choices
| Version | Method | Consideration |
|---|---|---|
| v1 | Time, clock sequence, node | May expose a MAC address; plain text sorting is not time sorting |
| v4 | 122 random bits | No embedded time or generation ordering |
| v5 | SHA-1 of namespace and name | Same namespace and name bytes give the same value |
| v7 | Leading Unix milliseconds | Supports time-oriented sorting but reveals time |
Choose for the use case
- Consider v4 for random IDs without time, or v7 for time-oriented storage. Even v7 cannot guarantee strict processing order across machines.
- Consider v5 for repeatable name-to-ID mapping. Agree on namespace, encoding, and normalization. It is not a secret token or a tamper-detecting signature.
- For v1 compatibility, inspect time and node handling. ULID and KSUID are separate formats. See the practical comparison.
Generation considerations
Use an established library and choose the version explicitly.
Check library behavior
- For random-based versions such as v4, choose an implementation using a cryptographically secure random generator.
- A random node in v1 avoids exposing a MAC address but does not conceal time.
- For v7, check same-millisecond generation and clock rollback behavior. Implementations may use some of the remaining 74 bits for counters or finer time.
Collision risk grows with count
Two independent, uniform v4 values match with probability 1 / 2^122. Across n values, the chance of at least one duplicate is approximately n(n−1) / (2 × 2^122) when small: about 9.4 × 10^-20 for one billion. See risk by count, and design unique-constraint handling and regeneration.
Typical uses
Use a UUID to identify which piece of data you mean.
Examples and authorization
- Order IDs, message IDs, and correlation IDs that connect logs.
- Client-generated UUIDs still require input validation and duplicate detection on storage.
- A UUID in a URL does not grant access. Authorize reads and writes. Use a mechanism designed for session tokens when that is the requirement.
Storage and operations
Agree on storage and interchange conventions so systems compare the same values.
Align storage and comparisons
- Choose a native UUID type, 16-byte binary, or text storage. Benchmark relevant indexes and queries instead of assuming one form is always faster.
- Agree on byte order for binary interchange and a consistent text representation such as lowercase.
- A shorter encoding for URLs should preserve all 128 bits; cutting off characters does not.
- See practical UUID tips for generation commands and storage details, or Unix time for timestamp basics.