UUID Versions Explained — v1 Through v7 Compared

Not all UUIDs are random. The version number — the digit after the third hyphen group — tells you how the UUID was generated and what information it contains. Choosing the wrong version can mean leaking server information (v1), getting no benefits of sorting (v4 in a database), or generating the wrong type of ID for your use case. Here is what each version does and when to use it.

UUID v4 — Random (The Right Default)

UUID v4 uses 122 bits of cryptographically random data. There is no embedded timestamp, no MAC address, no name-based hash — just random bits.

Format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx where 4 is the version digit and y is 8, 9, a, or b (variant bits).

Use when: You need unique IDs and have no requirement for sortability or determinism. Most web app primary keys, session IDs, correlation IDs, and API keys should be UUID v4.

Do not use when: You need sequential ordering for database index performance (use v7) or need deterministic IDs from a name (use v5).

UUID v1 — Timestamp and MAC Address (Avoid for New Projects)

UUID v1 embeds a 60-bit timestamp (100-nanosecond intervals since October 1582) and the generating machine's MAC address.

Format: tttttttt-tttt-1ttt-vrrr-mmmmmmmmmmmm where t = timestamp bits, v = variant, r = random clock sequence, m = MAC address.

Problem 1 — Privacy: The MAC address is embedded in every generated UUID, identifying the generating machine. In a cloud or containerized environment, the "MAC address" is a network interface that may be traceable back to a specific server or container.

Problem 2 — Ordering: The timestamp bytes are stored in a way that does not sort lexicographically by time — the low timestamp bits come first. IDs generated in sequence do not sort in insertion order.

Use when: Legacy systems that require it. For new projects, use v7 if you need time-ordering, or v4 if you do not.

UUID v5 — Deterministic from a Name (SHA-1)

UUID v5 generates a UUID deterministically from a namespace UUID and a name string. The same namespace + name always produces the same UUID — on any machine, at any time.

// JavaScript (uuid npm package):
import { v5 as uuidv5 } from 'uuid';

const MY_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'; // URL namespace
const id = uuidv5('https://example.com/user/123', MY_NAMESPACE);
// Always: 'a6edc906-2f9f-5fb2-a373-efac406f0ef2'

// Python:
import uuid
ns = uuid.UUID('6ba7b810-9dad-11d1-80b4-00c04fd430c8')
id = uuid.uuid5(ns, 'https://example.com/user/123')
# Always the same output for the same inputs

Use when:

• You need to generate the same UUID for the same entity across systems without a shared database
• Converting a legacy string ID to a UUID without storing a mapping table
• Creating stable content-addressable IDs from URLs or names

Standard namespaces are defined in RFC 4122: DNS (6ba7b810-9dad-11d1-80b4-00c04fd430c8), URL (6ba7b810-9dad-11d1-80b4-00c04fd430c8), OID, and X.500.

Sell Custom Apparel — We Handle Printing & Free Shipping

UUID v3 — Same as v5 but Uses MD5

UUID v3 works identically to v5 — deterministic generation from a namespace and name — but uses MD5 instead of SHA-1 for hashing.

MD5 is considered cryptographically broken. For new systems, always use v5 over v3. The only reason to use v3 is compatibility with a system that already generates v3 UUIDs and requires the same deterministic output.

// Python:
import uuid
ns = uuid.NAMESPACE_URL
id = uuid.uuid3(ns, 'https://example.com')  # v3 — MD5
id5 = uuid.uuid5(ns, 'https://example.com')  # v5 — SHA-1 (prefer this)

UUID v7 — Time-Ordered and Random (Best for Database Keys)

UUID v7 (RFC 9562, 2024) embeds a millisecond-precision Unix timestamp in the first 48 bits, followed by random data. This makes v7 UUIDs monotonically increasing — newer UUIDs are always greater than older ones when compared as bytes or strings.

Why this matters for databases: Sequential UUIDs insert at the end of a B-tree index rather than at random positions, dramatically reducing index fragmentation. This gives UUID v7 the performance characteristics of an auto-increment integer key with the uniqueness guarantees of UUID.

// JavaScript (uuid package v9+):
import { v7 as uuidv7 } from 'uuid';
const id = uuidv7();
// '01956b13-f000-7000-8000-000000000000' — time prefix visible

// Python (pip install uuid6):
import uuid6
id = uuid6.uuid7()

// PostgreSQL 17+:
SELECT uuidv7(); -- built-in function

Use when: You need UUID primary keys in a database and want good insert performance without switching to ULID or integer keys.

Trade-off: The timestamp prefix means two UUIDs generated close together are distinguishable as "close in time" — they are not as opaque as v4. For most use cases this is fine, but for IDs that must not reveal temporal information, use v4.

Choosing the Right UUID Version

Need	Use
Random, opaque ID — general purpose	v4
Database primary key with good insert performance	v7
Deterministic ID from a name or URL	v5
Same as v5 but legacy system requires MD5	v3
Legacy system requires v1	v1 (avoid for new work)

For the vast majority of applications: v4 for everything, v7 if you specifically care about database index performance. The other versions have narrow, specific use cases.

Frequently Asked Questions

What UUID version should I use for database primary keys?

UUID v7 for the best performance — it is monotonically increasing, reducing B-tree index fragmentation. UUID v4 works but causes random insertions across the index, which degrades performance at scale. UUID v1 is time-ordered but in the wrong byte order and leaks MAC addresses.

What is UUID v5 used for?

Generating the same UUID from the same input every time. Common uses: converting a string identifier to a UUID without a lookup table, generating stable IDs for content-addressed systems, or creating consistent IDs across multiple independent systems from a shared name.

Is UUID v7 widely supported?

Support is growing rapidly. PostgreSQL 17 added uuidv7() natively. The uuid npm package added v7 in v9. Python has uuid6 on PyPI. Most languages have library support. As of 2025-2026, v7 is production-ready for new projects.

Why is UUID v1 considered bad?

Two reasons: it embeds your MAC address (a privacy/security issue) and its bytes are not ordered by time in a way that sorts lexicographically (the low timestamp bits come first). UUID v7 solves both problems.

Can I use UUID v5 as a password or token?

No. UUID v5 is deterministic — anyone who knows your namespace and the input name can reproduce the UUID. It should only be used as an identifier, not as a secret. For secrets, use UUID v4 or crypto.randomBytes().