UUID Versions Explained — v1, v3, v4, v5, and v7

UUID has 8 defined versions, each with a different strategy. v4 (random) is the most common; v5 (deterministic) is best when you need the same ID for the same input; v7 (time-ordered) is the newest and best for databases.

Generate UUIDs with the UUID Generator.

UUID format

xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
                ↑        ↑
                M = version (1-8)
                N = variant (8, 9, a, or b for RFC 4122)

Example UUID v4:
550e8400-e29b-41d4-a716-446655440000
                ↑ 4 = version 4 (random)
                     ↑ a = variant (RFC 4122)

UUID v4 — Random

import { v4 as uuidv4 } from 'uuid';  // npm install uuid

uuidv4();  // "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
// 122 bits of random data

// Node.js built-in (no library needed):
import { randomUUID } from 'crypto';
randomUUID();  // Same format

// Browser:
crypto.randomUUID();  // Available in modern browsers

Use v4 when:

• IDs have no inherent meaning
• No need for time ordering or determinism
• Most common use case (user IDs, session IDs, record IDs)

UUID v5 — Deterministic (SHA-1 hash of namespace + name)

import { v5 as uuidv5 } from 'uuid';

// Standard namespaces:
const NAMESPACES = {
  DNS:  '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
  URL:  '6ba7b811-9dad-11d1-80b4-00c04fd430c8',
  OID:  '6ba7b812-9dad-11d1-80b4-00c04fd430c8',
  X500: '6ba7b814-9dad-11d1-80b4-00c04fd430c8',
};

// Same input → same UUID every time:
const emailUUID = uuidv5('alice@example.com', NAMESPACES.URL);
// Always: "67ef3c09-3e01-5a0f-9f3d-7c6fc6f6c4a0"

uuidv5('alice@example.com', NAMESPACES.URL);  // Same result
uuidv5('bob@example.com',   NAMESPACES.URL);  // Different UUID

// Custom namespace:
const MY_NAMESPACE = uuidv5('my-app', NAMESPACES.DNS);  // Generate your namespace

const productUUID = uuidv5('SKU-12345', MY_NAMESPACE);
// Same SKU → same UUID, always

Use cases for v5:

• Deduplicate records: same email always maps to same UUID
• Content-addressable IDs: URL → UUID (for caching)
• Generate stable IDs without a database lookup
• Idempotent API endpoints: POST with same data → same resource ID

UUID v3 — Like v5 but uses MD5

import { v3 as uuidv3 } from 'uuid';

// v3 = MD5 hash, v5 = SHA-1 hash
// Use v5 over v3: SHA-1 is more collision-resistant
// Only use v3 if you need to match an existing v3 UUID system

UUID v1 — Time-based (MAC address + timestamp)

import { v1 as uuidv1 } from 'uuid';

uuidv1();  // "2c5ea4c0-4067-11e9-8bad-9b1deb4d3b7d"

Issues with v1:

• Embeds MAC address → privacy leak (reveals your network card)
• Embeds timestamp → timing attack potential
• Not truly random → predictable by adversaries

When to use v1: Only for legacy systems that require it. New code should use v4 or v7.

UUID v7 — Time-ordered (ES2024)

import { v7 as uuidv7 } from 'uuid';

uuidv7();  // "018e50a9-9b24-7000-8000-4bc7e6c3b2c0"
// First 48 bits = Unix timestamp in ms
// UUID7s generated at the same time sort correctly

Why v7 beats v1 for databases:

• Time-ordered → B-tree index locality (inserts at the end, not random)
• No MAC address privacy issue
• Millisecond precision (v1 is 100-nanosecond Gregorian time from 1582)
• Better random component distribution

-- UUID v7 in PostgreSQL — efficient index:
CREATE TABLE events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),  -- pg14+ for v4
  -- For v7, generate in application and INSERT:
  -- id UUID PRIMARY KEY,
  created_at TIMESTAMP GENERATED ALWAYS AS (
    to_timestamp(
      (('x' || lpad(right(id::text, -4), 16, '0'))::bit(64)::bigint >> 16) / 1000.0
    )
  ) STORED
);

Summary comparison

Version	Method	Random?	Sortable?	Deterministic?	Use for
v1	Time + MAC	No	Yes	No	Legacy only
v3	MD5 hash	No	No	Yes	Legacy only
v4	Random	Yes	No	No	General purpose
v5	SHA-1 hash	No	No	Yes	Same name → same ID
v6	Reordered v1	No	Yes	No	v1 with better sort
v7	Unix time + random	Mostly	Yes	No	Databases (new)
v8	Custom	Custom	Custom	Custom	Application-defined

Related tools

• UUID Generator — generate any UUID version
• CUID2 Guide — alternative to UUID
• Hash Generator — SHA-1 and SHA-256 hashing (v5 internals)