UUID v5 Explained: Deterministic, Name-Based IDs

A teammate once opened a bug I still think about. Our nightly import job was creating duplicate records — same customers, fresh IDs every run, so the database happily treated last night's Acme Corp as a brand-new company again this morning. We'd reached for a random UUID v4 out of habit: random, unique, done. But 'unique every time' was exactly the wrong property. What we needed was the opposite — the same input producing the same ID, every run, forever. That's UUID v5, and once we switched, the duplicates stopped that night.

Deterministic, like a vending machine

A vending machine is deterministic. Punch B4 and you get the same granola bar today, tomorrow, and next year; punch A1 and you get the same soda. The slot code doesn't roll dice — it maps a fixed input to a fixed output. UUID v5 works exactly like that: feed it the same name and it hands back the same UUID every single time, on any machine, with no shared state and no coordination.

That's the entire difference from the UUID most people know. A UUID is a 128-bit identifier, and version 4 fills almost all of it with randomness. Version 5 fills it by hashing an input instead, which trades unpredictability for reproducibility.

How v5 builds an ID

A v5 UUID is derived from two things: a namespace and a name. The algorithm concatenates the namespace (itself a UUID) with the name, runs the result through SHA-1, and then forces the version and variant bits into place so the output is a well-formed UUID. Same namespace plus same name, same SHA-1 digest, same UUID — that's where the determinism comes from. (You can watch the hashing half of that in a SHA-1 generator: the same input always yields the same digest.)

There's a near-twin worth naming: version 3 does the identical dance but with MD5 instead of SHA-1. They're interchangeable in spirit, and since the hash here is used for structure rather than security, either works — but v5 is the one to prefer for new systems.

What the namespace is for

The namespace is the part people skip, and it's the clever bit. It scopes the name so you can reuse plain, simple names without fear of collision. The name alice inside a 'users' namespace produces a completely different UUID than alice inside an 'orders' namespace, because the namespace UUID feeds into the hash too.

The spec ships a few predefined namespaces for common cases — DNS names, URLs, ISO OIDs, and X.500 distinguished names — and you're encouraged to mint your own namespace UUID (a v4 is fine) for your application's private categories. Pick a namespace once, keep it constant, and every derived ID stays stable across services that share it.

When v5 earns its place

Reach for v5 when reproducibility is the feature, not a bug:

• Deriving stable IDs from natural keys. Turn a URL, an email, or a filename into a consistent UUID without storing a lookup table — the input is the lookup.
• Deduplication and idempotent imports. The exact problem from my war story: if the same source record always resolves to the same ID, re-running an import can't create duplicates.
• Agreement without coordination. Two independent systems that hash the same namespace and name will land on the identical UUID, no shared database or central authority required.

When v5 is the wrong tool

Determinism cuts both ways, so know the sharp edges:

• It's not a secret. Anyone who knows the namespace and name can recompute the exact UUID. Never use v5 for tokens, session IDs, or password-reset links — that's a job for a random v4 value or a Nano ID.
• It's not for hot database keys. v5 values are effectively random in sort order, so as a heavily-inserted primary key they fragment the index the same way v4 does. When insert performance matters, v7's time-ordering is the right call.
• The SHA-1 here isn't a security claim. It's used to spread inputs across the UUID space, not to protect anything — don't read it as 'v5 is cryptographically strong.'

Where v5 sits among the versions

Quick map: v4 is random (unique, unguessable), v5 is deterministic and name-based (reproducible from an input), and v7 is time-ordered (sortable, index-friendly). All three are the same 128-bit format under the hood — the same format Microsoft calls a GUID — so they validate identically in shape. To generate v4 and name-based values to experiment with, the UUID Generator produces them on demand, and you can confirm any UUID's structure with a regex tester (though a real parser should check the version nibble, as covered in UUID format and validation). One caveat worth remembering: because v5 is only as unique as its inputs, feeding it duplicate names will produce duplicate IDs — the uniqueness question shifts from the algorithm to your data.

The takeaway

UUID v5 is the deterministic member of the family: hash a namespace and a name with SHA-1, get the same UUID every time, anywhere, with no coordination. It shines for deriving stable IDs from natural keys, deduplicating, and making imports idempotent — and it's the wrong choice for anything that must be secret or that lives as a hot database key. Random when you need surprise, v5 when you need the same answer twice.