UUID v4 vs v5: Random Versus Name-Based Identifiers

How v5 works

v5 takes a namespace UUID and a name string, concatenates them, hashes with SHA-1, and formats 122 of the bits as a UUID. The same namespace and name always produce the same result — on any machine, in any language, forever.

v3 is the same design using MD5. Prefer v5; there is no reason to pick MD5 here, and the two are otherwise interchangeable.

import uuid
uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
# -> cfbff0d1-9375-5685-968c-48ce8b15ae17, always

Namespaces

RFC 9562 predefines four: DNS, URL, OID and X.500. They exist so that the same name in different contexts gives different UUIDs — example.com as a DNS name and as a URL are not the same thing.

For application data, generate one random v4 as your own namespace constant and keep it fixed. Changing it later changes every derived UUID, so treat it like a schema decision.

When v5 earns its place

Idempotent imports: derive the UUID from a stable external key, and re-running the import updates rather than duplicating.

Cross-system agreement: two services can compute the same identifier for the same entity without talking to each other.

Deterministic test fixtures, where a random id would make assertions unstable.

The trade-offs

v5 is not secret. Anyone who knows the namespace and the name can compute the UUID, so it must never be used where the identifier acts as an access token.

It is also only as unique as its input — the same name gives the same UUID, which is the point and also a collision if two different entities share a name.

And SHA-1 underneath is not a security concern here, since v5 is about determinism rather than integrity. But it does mean v5 UUIDs cannot be used as a security primitive.