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 caseWhy name-based UUID
Stable URL IDsuuidv5(url, URL_NS) — same URL → same UUID
DeduplicationSame event name → same UUID → idempotent insert
Content addressingFile hash → UUID for content-addressed storage
External entity IDsMap third-party IDs to UUIDs without a lookup table
Test fixturesDeterministic IDs make tests reproducible

Name-based vs random UUID comparison

PropertyUUID v5 (name-based)UUID v7 (time-ordered)
DeterministicYesNo
Time-orderedNoYes
Input requiredNamespace + nameNone (uses timestamp + random)
Collision riskSame input = same UUID74 random bits per ID
Use caseStable IDs for known entitiesPrimary keys for new records

Further reading

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.