When to Use UUID v4 vs v5?
UUIDs come in several versions. The two you'll use most often are Version 4 (random) and Version 5 (name-based, SHA-1). Choosing the right one affects uniqueness, reproducibility, and performance.
Version 4 — Random
Version 4 UUIDs are generated from random (or pseudo-random) numbers. Each call produces a new, unpredictable value. They're ideal when you need a unique ID and don't care about deriving it from a name or reproducing it later.
Use v4 when: creating new records (users, orders, sessions), generating tokens, or any case where you just need a unique identifier and will store it. Our generator and API support v4 by default.
Version 5 — Name-Based
Version 5 UUIDs are deterministic: you feed a namespace (a UUID) and a name (string), and the same inputs always produce the same UUID. They're defined in RFC 4122 using SHA-1.
Use v5 when: you need the same UUID for the same logical entity across systems (e.g. same UUID for "user@example.com" in every service), for cache keys, or for reproducible test data. You don't need to store the UUID if you can recompute it from namespace + name.
Comparison
- Uniqueness: v4 relies on randomness; v5 relies on the uniqueness of namespace + name.
- Reproducibility: v4 is not reproducible; v5 is, given the same namespace and name.
- Collisions: v4 collision risk is negligible with a good RNG; v5 has no practical collision risk if names are unique within the namespace.
Summary
Default to v4 for new IDs you'll store. Use v5 when you need stable, derivable identifiers (e.g. from email, URL, or resource name). For bulk random IDs, use our bulk generator; for validating existing UUIDs, use our validator.