UUID v5 / v3 Generator

About namespace UUIDs

Namespace UUIDs (versions 3 and 5) solve a problem distinct from the random UUIDs most people are familiar with: they produce the same output every time when given the same input. This determinism is the entire point. Instead of asking "give me a new unique identifier," you're asking "give me the identifier for this particular thing."

The mechanism is straightforward. You provide a namespace (itself a UUID, chosen to identify the domain you're working in) and a name (a string within that domain). The generator concatenates them, hashes the result with MD5 (for v3) or SHA-1 (for v5), and formats the hash into the UUID structure. Anyone, anywhere, given the same namespace and name will produce the same UUID. No coordination required.

This makes namespace UUIDs ideal for situations where you need stable identifiers derived from data that already exists. Common patterns include:

• Generating IDs from URLs, so the same URL always maps to the same UUID across systems;
• Creating consistent IDs from external keys during system integration, so two services agree on the identity of a record without needing to negotiate a shared mapping;
• Deduplicating records by content, where the same content should always produce the same identifier regardless of when it's processed;
• Producing stable references for hierarchical data, such as the path of a file within a tree.

v5 vs v3 — which should I use?

v5 (SHA-1) supersedes v3 (MD5). Both versions produce a UUID by hashing namespace_bytes || utf8(name) and forcing the version and variant bits. The only meaningful difference is the hash function — and SHA-1 has been the preferred choice since RFC 4122 in 2005.

Use v5 for any new system. RFC 9562 explicitly recommends it. It also gives you a tiny bit more collision resistance — SHA-1 is broken for adversarial collisions, but the 122 effective bits of a v5 UUID are random enough that incidental collisions remain astronomically unlikely.

Use v3 only when you need to reproduce existing v3 identifiers — e.g., interoperating with a legacy system that already issued v3 UUIDs. There is no scenario where v3 is the right choice for a new ID.

When to use name-based UUIDs at all

• Stable IDs from natural keys. "Give me the UUID for company.com" returns the same value forever, across machines, without coordination.
• Idempotent record creation. Derive a UUID from your input payload; re-runs of the same job produce the same ID and naturally upsert.
• Cross-system joins. Two services that derive UUIDs from the same canonical name will agree on the identifier without exchanging it.
• Not for anything random or unguessable — v5 of a known name is reproducible by anyone with that name. Use v4 if you need unpredictability.

Choosing a namespace

RFC 9562 §6.6 defines four standard namespaces:

• DNS   6ba7b810-9dad-11d1-80b4-00c04fd430c8 — for fully-qualified domain names
• URL   6ba7b811-9dad-11d1-80b4-00c04fd430c8 — for URLs
• OID   6ba7b812-9dad-11d1-80b4-00c04fd430c8 — for ISO object identifiers
• X.500 6ba7b814-9dad-11d1-80b4-00c04fd430c8 — for X.500 distinguished names

For application-specific data — internal entity types, tenant identifiers, custom record keys — generate a fresh UUID once (a v4 will do) and use that as your custom namespace. Document the namespace somewhere persistent so your team and any integrators can produce matching IDs. Treat it like a schema version: changing the namespace later means all your derived IDs change too.

What namespace UUIDs are not for

Namespace UUIDs are identifiers, not secrets. Anyone who knows the namespace and the name can produce the UUID. This makes them unsuitable as:

• Session tokens or authentication credentials;
• API keys or shared secrets;
• Anti-enumeration identifiers (where you want IDs to be unguessable from external information).

If you need an identifier whose value cannot be predicted by someone who knows the underlying data, use UUID v4, a NanoID with sufficient length, or a purpose-built random token.

Generating in code

using System.Security.Cryptography;
using System.Text;

static Guid Uuid5(Guid ns, string name)
{
    Span<byte> nsBytes = stackalloc byte[16];
    ns.TryWriteBytes(nsBytes, bigEndian: true, out _);
    var input = new byte[16 + Encoding.UTF8.GetByteCount(name)];
    nsBytes.CopyTo(input);
    Encoding.UTF8.GetBytes(name, input.AsSpan(16));
    var hash = SHA1.HashData(input);
    var uuid = hash.AsSpan(0, 16).ToArray();
    uuid[6] = (byte)((uuid[6] & 0x0F) | 0x50);
    uuid[8] = (byte)((uuid[8] & 0x3F) | 0x80);
    return new Guid(uuid, bigEndian: true);
}

import uuid
id = uuid.uuid5(uuid.NAMESPACE_DNS, "www.example.com")
# 2ed6657d-e927-568b-95e1-2665a8aea6a2

FAQ