Understanding UUID Versions and When to Use Each One

If you've ever generated a UUID and wondered what all those numbers mean — you're not alone. UUIDs (Universally Unique Identifiers) look like random strings, but there's real structure behind them. Understanding that structure helps you choose the right version for your system.

What is a UUID?

A UUID is a 128-bit identifier written as 32 hexadecimal digits separated by hyphens: f47ac10b-58cc-4372-a567-0e02e2d5f6b1. There are 2¹²⁸ possible UUIDs — enough to assign one to every atom in the human body and still have plenty left over.

The format is standardized as RFC 4122. There are several versions, each generated differently and serving different purposes.

UUID v1 — Time + Node

// Version 1: timestamp + MAC address
// Example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8

UUID v1 combines:

• A 60-bit timestamp (UTC timestamp in 100-nanosecond intervals since October 1582)
• A 14-bit clock sequence (to handle clock drift)
• A 48-bit node identifier (usually the MAC address of the generating machine)

Strengths:

• Time-ordered — later UUIDs sort after earlier ones in most implementations
• Contains the generating machine's identity (useful for audit logs)

Weaknesses:

• Leaks the MAC address of the generating machine (privacy concern)
• Reveals approximately when and where a UUID was created
• Clock sequence handling adds complexity

When to use: Internal systems where time-ordering matters and privacy is not a concern. Some databases (Cassandra, RethinkDB) use v1 UUIDs as primary keys for locality.

UUID v4 — Random

// Version 4: cryptographically random
// Example: f47ac10b-58cc-4372-a567-0e02e2d5f6b1

UUID v4 is generated using a cryptographically strong random number generator. 122 of the 128 bits are random; 6 bits are fixed to indicate the version (4) and variant.

Strengths:

• True randomness — no information about the generator is leaked
• No coordination needed between machines
• Simple to generate

Weaknesses:

• Not time-ordered — new rows get "random" positions in indexes
• ~122 bits of entropy sounds like a lot but some implementations have weak RNGs (always use crypto.randomUUID() in Node.js or crypto.getRandomValues() in browsers)
• Sequential inserts are random I/O for rotating storage

When to use: Default choice for most new systems. Default for PostgreSQL (gen_random_uuid()), JavaScript (crypto.randomUUID()), Python (uuid.uuid4()). Works well when you don't need to infer anything from the ID itself.

UUID v5 — Name-based with SHA-1

// Version 5: namespace + name, hashed with SHA-1
import { createUUIDv5 } from './uuid-v5.js';

const NAMESPACE_URL = '6ba7b811-9dad-11d1-80b4-00c04fd430c8';
const uuid = createUUIDv5(NAMESPACE_URL, 'https://toolblip.com/user/123');
// Produces deterministic UUID for this name within this namespace

UUID v5 is generated by hashing a namespace identifier (UUID) and a name using SHA-1. The same namespace + name always produces the same UUID.

Strengths:

• Deterministic — reproducible across systems
• No networking required (unlike v1)
• Namespaced — you can define your own namespaces and avoid collisions

Weaknesses:

• Not sortable
• SHA-1 is considered cryptographically weakened (though still fine for non-security uses)

When to use: Generating stable IDs for external resources (webhooks, OAuth subject identifiers, content-addressable storage). If you need the same ID for the same input every time, v5 is the answer.

UUID v7 — Time-ordered (New Standard)

// Version 7: unix timestamp + random bits (recommended for most use cases)
// Example: 0191a1e0-9e3b-7f3a-a567-0e02e2d5f6b1

UUID v7 is the new standard (RFC draft), designed to combine the best of v1 and v4:

• First 48 bits: 32-bit unix timestamp (milliseconds since epoch)
• Next 12 bits: nanoseconds within the second
• Remaining bits: random

Strengths:

• Time-ordered — sorts by generation time
• No information leakage (random bits don't reveal the machine)
• URL-safe (no special characters)
• Works perfectly as a primary key — new rows get sequential positions near existing ones

Weaknesses:

• Relatively new — not all languages/frameworks have native support yet
• Requires a good entropy source for the random bits

When to use: New projects where you want time-ordering AND good distribution. PostgreSQL 13+, CockroachDB, MongoDB, and SQLite (via extension) support v7. JavaScript doesn't have native v7 yet — use a library like ulidx or uuid-time.

Quick Comparison

Version	Time-ordered	Privacy	Deterministic	Notes
v1	Yes	No (MAC)	No	Leaks machine identity
v4	No	Yes (random)	No	Default choice for most cases
v5	No	Yes (hashed)	Yes	Good for stable external IDs
v7	Yes	Yes (random)	No	Best of both worlds

A Note on UUID Collisions

UUID collisions are statistically impossible for any realistic workload. Even with 1 trillion UUIDs v4 generated per second, the probability of a collision is ~10⁻¹⁸. You'd have better luck winning the lottery every second for the lifetime of the universe.

Practical Recommendations

For most new work — UUID v4. It's the default in most frameworks, requires no thought, and works well.

For database primary keys where insert locality matters — UUID v7. Time-ordered UUIDs prevent random I/O on every insert, which matters at scale with rotating storage. CockroachDB and recent PostgreSQL versions support v7 natively.

For generating IDs from external strings — UUID v5. OAuth subject identifiers, content hashes, GitHub-style stable IDs for external resources.

For legacy systems or distributed databases that benefit from time-ordering — UUID v1. Rarely needed in new development.

JavaScript Implementation

// Generate a v4 UUID (Node.js 19+, all modern browsers)
const id = crypto.randomUUID();
console.log(id); // "f47ac10b-58cc-4372-a567-0e02e2d5f6b1"

// Verify it's valid
const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
console.log(UUID_REGEX.test(id)); // true

Useful Tool

Generate UUIDs instantly in your browser — no data leaves your device. Try our UUID Generator tool.

---

No data leaves your browser. All UUID generation happens client-side using the Web Crypto API.