Name-based UUIDs (v3 and v5) produce the same UUID every time for the same inputs. This determinism is the feature — it enables stable identifiers for known entities without a database lookup, content-addressable storage, and idempotent ID generation across distributed systems.
How name-based UUIDs work
UUID v5(namespace, name):
1. Concatenate: namespace_bytes (16) + name_utf8_bytes (N)
2. Hash with SHA-1: 20-byte digest
3. Take first 16 bytes
4. Set version nibble to 0b0101 (version 5)
5. Set variant bits to 0b10
6. Format as standard UUID string
The same namespace + name always yields the same UUID, regardless of when or where the function runs.
TypeScript with the uuid package
import { v5 as uuidv5, v3 as uuidv3 } from 'uuid';
// Standard namespaces
const DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
// UUID v5 — SHA-1 based (preferred over v3)
const domainUuid = uuidv5('example.com', DNS);
// '9073926b-929f-31c2-abc9-fad77ae3e8eb' — always the same
const urlUuid = uuidv5('https://example.com/page', URL);
// UUID v3 — MD5 based (legacy use only)
const legacyUuid = uuidv3('example.com', DNS);
// Custom namespace for your application
const MY_APP_NS = uuidv5('myapp.com', DNS); // use your own domain as namespace root
const productUuid = uuidv5('SKU-12345', MY_APP_NS);
// Same SKU always gets the same UUID — stable across deploys
Python example
import uuid
DNS_NS = uuid.NAMESPACE_DNS
URL_NS = uuid.NAMESPACE_URL
# UUID v5 — deterministic from namespace + name
domain_id = uuid.uuid5(DNS_NS, 'example.com')
print(domain_id) # 9073926b-929f-31c2-abc9-fad77ae3e8eb
# Create a custom namespace for your application
app_ns = uuid.uuid5(DNS_NS, 'myapp.example.com')
product_id = uuid.uuid5(app_ns, 'SKU-12345')
# Identical across all environments and deploys
Use cases
| Use case | Why name-based UUID |
|---|---|
| Stable URL IDs | uuidv5(url, URL_NS) — same URL → same UUID |
| Deduplication | Same event name → same UUID → idempotent insert |
| Content addressing | File hash → UUID for content-addressed storage |
| External entity IDs | Map third-party IDs to UUIDs without a lookup table |
| Test fixtures | Deterministic IDs make tests reproducible |
Name-based vs random UUID comparison
| Property | UUID v5 (name-based) | UUID v7 (time-ordered) |
|---|---|---|
| Deterministic | Yes | No |
| Time-ordered | No | Yes |
| Input required | Namespace + name | None (uses timestamp + random) |
| Collision risk | Same input = same UUID | 74 random bits per ID |
| Use case | Stable IDs for known entities | Primary keys for new records |
Further reading
- UUID v3 — MD5 Name-Based UUID
- UUID v5 — Deterministic Namespace-Based UUIDs
- Namespace — UUID Namespace Concept
- UUID Namespace — DNS, URL, OID, X500
- UUID v4 vs UUID v7
Frequently asked questions
What is the difference between UUID v3 and UUID v5?
UUID v3 uses MD5 hashing; UUID v5 uses SHA-1. SHA-1 is stronger than MD5 for collision resistance, so UUID v5 is preferred for new systems. Both are deterministic — the same namespace + name always produces the same UUID. Neither version is suitable for security-sensitive applications because neither MD5 nor SHA-1 is a cryptographic hash function for this purpose. See UUID v3 — MD5 Name-Based UUID.
When should I use name-based UUIDs instead of UUID v7?
Use name-based UUIDs (v3 or v5) when you need deterministic IDs for known inputs — for example, a stable UUID for a URL, a DNS name, or a product SKU. Use UUID v7 when you need time-ordered unique IDs for new records. Name-based UUIDs are not suitable for primary keys of user-created records because two records with the same name would get the same UUID. See UUID v4 vs UUID v7.
What are the standard UUID namespaces?
RFC 9562 defines four standard namespace UUIDs: DNS (6ba7b810-9dad-11d1-80b4-00c04fd430c8), URL (6ba7b811-9dad-11d1-80b4-00c04fd430c8), OID (6ba7b812-9dad-11d1-80b4-00c04fd430c8), and X.500 DN (6ba7b814-9dad-11d1-80b4-00c04fd430c8). You can also define custom namespace UUIDs for application-specific use. See UUID Namespace — DNS, URL, OID, X500.