What is a UUID and how does it work?

A UUID (Universally Unique Identifier), also called a GUID in Microsoft ecosystems, is a 128-bit identifier designed so that anyone can generate one, anywhere, without coordination, and practically never collide with anyone else's. That property makes UUIDs a natural fit for database keys in distributed systems, request and trace IDs, file names and message IDs.

Anatomy of a UUID

A UUID is written as 32 hexadecimal digits in five groups separated by hyphens:

text
123e4567-e89b-42d3-a456-426614174000
              ^    ^
              |    variant (8, 9, a or b)
              version (4)

• The version digit (the first digit of the third group) says how the UUID was generated.
• The variant bits (the first digit of the fourth group) say which UUID layout is used. For standard UUIDs, this digit is 8, 9, a or b.
• The remaining 122 bits, in a version 4 UUID, are random.

UUIDs are case-insensitive. 123E4567-... and 123e4567-... are the same UUID, but RFC 9562 recommends lowercase output.

The versions you'll meet

Version	How it's generated	Typical use
v1	Timestamp + node ID (often derived from a MAC address)	Legacy systems; leaks creation time
v3 / v5	Hash (MD5 / SHA-1) of a namespace and a name	Same input always gives the same UUID
v4	122 random bits	The default choice for most applications
v6	Like v1, reordered so it sorts by time	Rarely used; v7 is preferred
v7	Unix timestamp in milliseconds + random bits	Time-ordered IDs for database keys

Versions 6, 7 and 8 were standardized in RFC 9562 (2024), which replaced the original RFC 4122.

Can two UUIDs collide?

For version 4, there are 2^122 (about 5.3 × 10^36) possible values. By the birthday problem, you'd need to generate roughly 2.7 quintillion (2.7 × 10^18) UUIDs before the chance of even one duplicate reached 50%. At a billion UUIDs per second, that takes about 86 years.

In practice, collisions come from bad random number generators, not bad luck. Always use a cryptographically secure source: crypto.randomUUID() in browsers and Node.js, uuid.uuid4() in Python, or UUID.randomUUID() in Java.

UUIDs as database keys

UUIDs are convenient primary keys because clients can create records offline, IDs from different databases never clash, and IDs don't reveal how many rows you have. There are trade-offs:

• Index locality. Random v4 values scatter inserts across a B-tree index, which can slow down heavy write loads. v7 UUIDs start with a timestamp, so new rows land near each other, much like an auto-increment key.
• Size. A UUID takes 16 bytes as binary but 36 as text. Use a native uuid type (PostgreSQL) or BINARY(16) (MySQL) rather than VARCHAR(36).
• Readability. UUIDs are hard to read aloud or type. For user-facing references such as order numbers, use a separate short code.

UUIDs in JSON and APIs

UUIDs are always sent as strings in JSON ("id": "123e4567-e89b-42d3-a456-426614174000"), and they're a good choice for public API identifiers because they're opaque and can't be guessed by incrementing. Just don't treat them as secrets: a v4 UUID is hard to guess, but it isn't a security token. See API JSON best practices for more on IDs.

Generate UUIDs

The UUID Generator creates v4 (random) or v1 (time-based) UUIDs in your browser, up to 500 at a time, in uppercase or lowercase, with or without hyphens. In code:

javascript
crypto.randomUUID(); // browsers and Node.js 19+

python
import uuid
str(uuid.uuid4())

sql
SELECT gen_random_uuid(); -- PostgreSQL 13+