UUID Generator

How the UUID Generator works

Uuid generator: how the names are built

A UUID is a 128-bit number written as 32 hexadecimal digits in five hyphenated groups. The point of it is that you can mint one anywhere — on a phone that has been offline for a week, in a test that runs a thousand times a second, in two datacentres at once — and be confident nobody else has ever produced the same one. No coordination, no central counter, no round trip to ask the database what the next number is.

Version 4 is random, and that is all it is. 122 of the 128 bits come from a cryptographically secure random number generator; the other six are fixed markers saying "version 4" and "variant 1". The collision risk is the birthday problem on a space of 2¹²². To reach a one in a billion chance of a single duplicate you would need to generate around 10¹⁶ of them. You will not collide. This is the version to use when the identifier should reveal nothing at all — not when it was made, not by which machine, not how many came before it.

Version 7 puts the clock in front. The first 48 bits are a Unix millisecond timestamp, and the remaining 74 are random. Because the timestamp is big-endian and leads the value, sorting v7 UUIDs as text or as bytes sorts them by creation time — with one caveat worth knowing: two made in the same millisecond differ only in their random tail, so their order relative to each other is arbitrary. Everything else about them — uniqueness, the fact that you can generate them offline — is unchanged.

Why that matters, and it is the thing most people learn the hard way. Databases store rows in B-tree indexes, and a B-tree is cheapest to maintain when new keys arrive at the right-hand edge. An auto-incrementing integer does exactly that: every insert lands on the page already in memory. A v4 UUID lands in a uniformly random position instead, so each insert dirties a different page, the cache stops helping, and pages split down the middle rather than filling. On a large table under sustained insert load this is not a rounding error — it is the difference between a write path that keeps up and one that does not. It is the reason "don't use random UUIDs as your clustered primary key" became folklore. Version 7 exists to end that argument: you keep the generate-anywhere property and you get back the sequential insert pattern.

The cost of v7 is that it leaks time. Anyone holding one of your identifiers can read the millisecond it was created, and holding two tells them how far apart the two records were made. For an order ID that is usually harmless and occasionally useful. For a password-reset token, a share link or anything an outsider will see, it is information you did not mean to publish — use v4 there, or a random token that is not a UUID at all.

The other versions. Version 1 is the original, built from a timestamp and the machine's MAC address, which is why it fell out of favour. Versions 3 and 5 hash a name inside a namespace, so the same input always yields the same UUID — handy for deriving a stable ID from something you already have. Version 6 reorders v1's timestamp to make it sortable. For new work the practical choice is between 4 and 7, which is why those are the two offered here.

Related tools