UUID v5 Generator (Name Based, SHA-1)

What a UUID v5 is

Version 5 is the name based UUID. Instead of random bits, it hashes two inputs with SHA-1: a namespace, which is itself a UUID, and a name, which is any string. The first 128 bits of the hash become the UUID, with the version and variant bits overwritten. Feed in the same namespace and name anywhere in the world and you get the same UUID. Change one character and you get a completely different one.

That determinism is the whole point. A random UUID answers "give me a new id". A v5 UUID answers "give me the id for this thing".

The four standard namespaces

RFC 9562 defines namespaces for common kinds of names. This generator has them built in, or you can paste any UUID as a custom namespace.

For your own data, mint one random UUID, store it as your application's namespace, and use it for every v5 you make. That keeps your ids from ever colliding with someone else's ids for the same name.

When to use v5

• Mapping external keys to UUIDs. A customer number from a legacy system, an ISBN, a URL. Any service can compute the UUID without asking a central database.
• Idempotent imports. Run the same import twice and each record gets the same id, so the second run updates instead of duplicating.
• Content addressing. The id of a document is derived from its canonical name, so two systems agree on it without talking.
• Stable ids in tests and fixtures. No more hard coded random strings.

Do not use v5 when the input is secret. SHA-1 is one way, but if the set of possible names is small, someone can hash all of them and match. And do not use it when you simply need unique ids, that is what v4 and v7 are for.

v5 or v3

Version 3 is the same idea with MD5 instead of SHA-1. Both are fine for generating identifiers, because collision resistance of the hash barely matters at 122 bits. Prefer v5 unless you must match an existing system that used v3, such as ids produced by Java's UUID.nameUUIDFromBytes.

Generate a v5 UUID in code

// JavaScript, uuid package
import { v5 as uuidv5 } from "uuid";
const id = uuidv5("example.com", uuidv5.DNS);

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

-- PostgreSQL with the uuid-ossp extension
SELECT uuid_generate_v5(uuid_ns_dns(), 'example.com');

Try the same input above with the DNS namespace and you will get exactly that Python value. That is the property in action.

Frequently asked questions

Can I get the name back out of a v5 UUID?

No. It is a hash, and only 122 bits of it survive, so there is no way to reverse it. If you need to look up the name, store the mapping.

Does the same name in a different namespace give the same UUID?

No. The namespace is hashed together with the name, so example.com under DNS and example.com under URL produce different values. Choose one namespace per kind of name and stick to it.

Is SHA-1 a problem here?

SHA-1 is broken for signatures, where an attacker wants two inputs with the same hash. For deriving identifiers from names you control, that attack does not apply. Every major library still implements v5 with SHA-1 because the RFC defines it that way.