Definition
UUID v3 is a name-based UUID that uses MD5 (128-bit hash) to derive a deterministic identifier from two inputs: a namespace UUID and a name string. Defined in RFC 9562 §5.3 (and its predecessor RFC 4122), UUID v3 is identical to UUID v5 except for the hash function — v3 uses MD5, v5 uses SHA-1.
Key property: The same namespace + name pair always produces the same UUID v3 value, on any machine, in any implementation.
Byte layout
Bits 0–47: md5_high — high 48 bits of the 128-bit MD5 hash
Bits 48–51: version — 0011 = "3"
Bits 52–63: md5_mid — next 12 bits of MD5
Bits 64–65: variant — 10 (RFC 9562)
Bits 66–127: md5_low — remaining 62 bits of MD5
After computing MD5 over (namespace_bytes || name_bytes), the version nibble is overwritten with 0011 and the variant bits with 10 — exactly 6 bits of the hash output are lost. See UUID Byte Layout for the full bit diagram.
Generation
import { v3 as uuidv3 } from 'uuid';
const DNS_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
// Same inputs always produce the same UUID
const id = uuidv3('example.com', DNS_NAMESPACE);
// → '9073926b-929f-31c2-abc9-fad77ae3e8eb'
import uuid
id = uuid.uuid3(uuid.NAMESPACE_DNS, 'example.com')
# → UUID('9073926b-929f-31c2-abc9-fad77ae3e8eb')
import "github.com/google/uuid"
id := uuid.NewMD5(uuid.NameSpaceDNS, []byte("example.com"))
// → 9073926b-929f-31c2-abc9-fad77ae3e8eb
All three produce the same UUID — this cross-language reproducibility is the main value of name-based UUIDs. See UUID DNS Namespace for the pre-defined namespace constants.
UUID v3 vs UUID v5
| UUID v3 | UUID v5 | |
|---|---|---|
| Hash | MD5 (128 bits) | SHA-1 (160 bits) |
| RFC section | §5.3 | §5.5 |
| Deterministic | Yes | Yes |
| Cryptographic status | Broken — collision attacks known | Weak — use SHA-256 for new crypto |
| Recommendation | Legacy interoperability only | Preferred for name-based UUIDs |
For a completely new system, consider UUID v8 with a truncated SHA-256 payload — see UUID v8 — Custom Layout.
Use cases
- Content deduplication —
uuidv3(url, URL_NAMESPACE)produces the same ID for the same URL across all services; duplicate URLs produce duplicate IDs that fail a unique constraint on INSERT. - Legacy system compatibility — existing systems that already store UUID v3 values require new clients to reproduce the same IDs from the same inputs.
- Deterministic test fixtures — generate predictable IDs in tests without random seeds. See UUID Testing Strategies.
Limitations
- MD5 is broken — chosen-prefix collision attacks are practical. Do not use UUID v3 where the name input can be attacker-controlled.
- Not random — UUID v3 does not protect the name or namespace from reverse-engineering. Given the UUID, an attacker who knows the namespace can brute-force the name for short inputs.
- Not time-sortable — UUID v3 sorts in no meaningful order. For time-ordered IDs, use UUID v7. See UUID v4 vs v7.
Related terms
- UUID v5 — Deterministic — SHA-1 alternative, preferred over v3
- UUID Namespace — the namespace input to v3 and v5
- UUID DNS Namespace — the pre-defined DNS namespace constant
- UUID Namespaces Guide — full implementation guide
- UUID Security — cryptographic properties of each version
External references
Frequently asked questions
When should I use UUID v3 instead of UUID v5?
Prefer UUID v5 (SHA-1) over UUID v3 (MD5) for all new work. MD5 is cryptographically broken — it is vulnerable to collision attacks and pre-image attacks. UUID v3 is only relevant when you must interoperate with a legacy system that already uses UUID v3 values and you need to reproduce the same IDs. See UUID Namespaces for the v5 implementation.
Is UUID v3 safe to use as a database primary key?
UUID v3 is deterministic — the same input always produces the same UUID. For use as a primary key, this is usually a feature (deduplication, idempotency), not a bug. The MD5 weakness is a collision risk for adversarial inputs — if an attacker controls the name input, they may be able to engineer a collision. For non-adversarial, controlled inputs (fixed domain names, internal resource paths), UUID v3 is functionally safe as a primary key. Prefer UUID v5 or a custom UUID v8 with SHA-256 for new systems. See UUID Security.