UUID v5 — Deterministic UUIDs from a Namespace and Name

UUID v4 is unpredictable by design. UUID v5 is the opposite — given the same two inputs (a namespace UUID and a name string), it always produces the same UUID. This makes it useful for content-addressed identifiers, legacy ID migration, and cross-system synchronization without a shared database.

How UUID v5 Works

UUID v5 hashes the namespace UUID and the name string together using SHA-1, then formats the result as a UUID with the version bits set to 5 and the variant bits set to the RFC 4122 standard variant.

The algorithm:

1. Concatenate the namespace UUID bytes and the name bytes
2. Compute the SHA-1 hash of the concatenation
3. Take the first 16 bytes of the hash
4. Set bits to indicate version 5 and the RFC variant
5. Format as the standard UUID string

Because SHA-1 is deterministic, the same inputs always produce the same output. Because the namespace is part of the input, the same name in different namespaces produces different UUIDs — preventing collisions across different ID spaces.

Standard UUID v5 Namespaces

RFC 4122 defines four standard namespace UUIDs you can use directly:

Namespace	UUID	Use for
DNS	6ba7b810-9dad-11d1-80b4-00c04fd430c8	Domain names
URL	6ba7b811-9dad-11d1-80b4-00c04fd430c8	URLs
OID	6ba7b812-9dad-11d1-80b4-00c04fd430c8	ISO OID strings
X.500	6ba7b814-9dad-11d1-80b4-00c04fd430c8	X.500 DN strings

You can also define your own namespace by generating any UUID v4 and using it consistently. The important thing is that your namespace is fixed and known to all systems that need to reproduce the same UUIDs.

Sell Custom Apparel — We Handle Printing & Free Shipping

Generate UUID v5 in JavaScript

import { v5 as uuidv5 } from 'uuid';

// Using a standard namespace:
const URL_NAMESPACE = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';

// Same name always produces the same UUID:
const id1 = uuidv5('https://example.com/user/123', URL_NAMESPACE);
const id2 = uuidv5('https://example.com/user/123', URL_NAMESPACE);
console.log(id1 === id2); // true — always the same

// Different names produce different UUIDs:
const otherId = uuidv5('https://example.com/user/456', URL_NAMESPACE);
console.log(id1 === otherId); // false

// Custom namespace (a UUID v4 you generated and fixed):
const MY_APP_NAMESPACE = 'a8098c1a-f86e-11da-bd1a-00112444be1e';
const productId = uuidv5('product-sku-ABC123', MY_APP_NAMESPACE);

Generate UUID v5 in Python

import uuid

# Using the built-in URL namespace:
id1 = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/user/123')
id2 = uuid.uuid5(uuid.NAMESPACE_URL, 'https://example.com/user/123')

print(id1 == id2)  # True — always the same
print(id1)         # a6edc906-2f9f-5fb2-a373-efac406f0ef2 (always)

# Built-in namespace constants:
uuid.NAMESPACE_DNS  # 6ba7b810-9dad-11d1-80b4-00c04fd430c8
uuid.NAMESPACE_URL  # 6ba7b811-9dad-11d1-80b4-00c04fd430c8
uuid.NAMESPACE_OID  # 6ba7b812-9dad-11d1-80b4-00c04fd430c8
uuid.NAMESPACE_X500 # 6ba7b814-9dad-11d1-80b4-00c04fd430c8

# Custom namespace:
MY_NAMESPACE = uuid.UUID('a8098c1a-f86e-11da-bd1a-00112444be1e')
product_id = uuid.uuid5(MY_NAMESPACE, 'product-sku-ABC123')

Real Use Cases for UUID v5

Legacy ID migration — You have a system with string IDs like "user-123" and want to migrate to UUID primary keys without changing all foreign key references or importing a mapping table. Use uuidv5(MY_NAMESPACE, "user-123") to derive a stable UUID for each legacy ID. Any system that knows the namespace can reproduce the same UUID from the same string.

Cross-system consistency — Two microservices need to refer to the same entity (a product, a user) without a shared database. If both use the same namespace and the same canonical name/URL for the entity, they independently generate the same UUID.

Content-addressable IDs — Generate a stable ID for a document based on its URL or canonical key. The UUID changes only if the key changes, and stays the same if the document is re-fetched or re-imported.

What NOT to use UUID v5 for — Any context requiring secrecy or unpredictability: session tokens, password reset links, API keys, access tokens. UUID v5 is reproducible by anyone with the namespace and name — it is an identifier, not a secret.

Frequently Asked Questions

What is the difference between UUID v4 and UUID v5?

UUID v4 is random — a different value every time, unpredictable. UUID v5 is deterministic — given the same namespace and name, always produces the same UUID. Use v4 for unique IDs, use v5 for stable IDs derived from known inputs.

Does UUID v5 guarantee no collisions?

No guarantee — SHA-1 can theoretically produce the same hash from different inputs (a collision), but this is cryptographically impractical. In real applications, UUID v5 collisions are not a concern. However, if your namespace is different, the same name will produce a different UUID.

Should I use UUID v3 or v5?

Use UUID v5. They work the same way, but v5 uses SHA-1 while v3 uses MD5. MD5 has known weaknesses. There is no reason to use v3 for new systems — use v5.

Can I use UUID v5 as a primary key?

Yes, with care. UUID v5 values are deterministic, which means they are not secret — anyone who can guess the namespace and name can predict the UUID. This is usually fine for internal primary keys but not for public-facing identifiers that need to be unguessable.

How do I pick a custom namespace for UUID v5?

Generate any UUID v4 once and record it permanently as your application's namespace UUID. Use this same value in all systems that need to generate consistent UUID v5 values. Never change the namespace — changing it changes all generated UUIDs.