UUID Guide: Understanding
Versions, Formats & Best Practices

1. What is a UUID?

UUID (Universally Unique Identifier) is a 128-bit identifier designed to be unique across all computers, all time, without requiring a central authority. Also known as GUID (Globally Unique Identifier) in Microsoft ecosystems.

Key Characteristics:

• 128 bits: Represented as 32 hexadecimal characters
• Globally unique: No central coordination needed
• Standardized: Defined in RFC 4122 (and RFC 9562 for v7)
• Platform-independent: Works across all systems

Common Use Cases:

• Database primary keys
• Distributed system identifiers
• Session tokens and correlation IDs
• File and resource naming
• API request tracking

2. UUID Format and Structure

UUIDs follow a standard format: 32 hexadecimal digits displayed as 8-4-4-4-12 groups separated by hyphens.

Version and Variant Indicators:

Look at the 13th character (M) to identify the version:

• xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx → Version 1
• xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxxxxxx → Version 4
• xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx → Version 7

The variant (N) indicates the UUID variant. For standard UUIDs, it starts with 8, 9, a, or b.

3. UUID Versions Explained

Version 1: Timestamp + MAC Address

Combines 60-bit timestamp (100-nanosecond intervals since Oct 15, 1582) with MAC address. Privacy concern: Exposes when and where the UUID was created.

// v1 structure reveals information
f81d4fae-7dec-11d0-a765-00a0c91e6bf6
           ↑          ↑
     timestamp    MAC address

Version 4: Random

122 bits of randomness (6 bits reserved for version/variant). Most commonly used. Simple, no information leakage, but not sortable.

// v4 - pure randomness
f47ac10b-58cc-4372-a567-0e02b2c3d479
              ↑    ↑
           version variant (4 and 8/9/a/b)

Version 5: Name-Based (SHA-1)

Deterministic: same namespace + name always produces the same UUID. Useful for generating consistent IDs from known data.

// Same input = same UUID
uuid_v5(DNS_NAMESPACE, "example.com") → always same result
uuid_v5(URL_NAMESPACE, "https://example.com/page") → always same result

Version 7: Time-Ordered Random (Recommended)

48-bit Unix timestamp (milliseconds) + 74 bits of randomness. Best of both worlds: sortable by creation time while being mostly random. Ideal for database primary keys.

// v7 - sortable by time, generated at the same millisecond
01932c08-e844-7d3f-8d5e-9c1b5d62a3e8 (earlier)
01932c08-e845-7a2b-9f3c-8d4e7a6b5c9d (later within same ms)
         ↑
    timestamp (ms since Unix epoch)

4. Which UUID Version Should I Use?

Decision Flowchart:

Need deterministic IDs? → UUID v5
Need time-sortable IDs? → UUID v7
Need maximum randomness? → UUID v4
Legacy system compatibility? → Match existing version
Default for new projects → UUID v7 (or v4 if unsupported)

5. Collision Probability

The question everyone asks: Can two UUIDs ever be the same?

The Math:

Perspective:

• Generating 1 billion UUIDs per second for 86 years gives ~50% collision chance
• Generating 1 trillion UUIDs = 0.00000000006% collision chance
• You're more likely to be struck by lightning while winning the lottery

6. UUIDs in Databases

Pros of UUID Primary Keys:

• ✅ Generate IDs client-side (no round-trip to database)
• ✅ Easy database merging and sharding
• ✅ No enumeration attacks (can't guess next ID)
• ✅ Hide row count from API consumers

Cons of UUID Primary Keys:

• ❌ Larger than integers (16 bytes vs 4-8 bytes)
• ❌ Random UUIDs cause index fragmentation (B-tree)
• ❌ Less human-readable for debugging
• ❌ Slightly slower joins and lookups

Database-Specific Storage:

PostgreSQL Example:

-- Enable UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

-- Create table with UUID primary key
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    -- or for v7: gen_random_uuid() in PG 13+
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- Insert with auto-generated UUID
INSERT INTO users (email) VALUES ('user@example.com');

-- Or specify UUID
INSERT INTO users (id, email) 
VALUES ('550e8400-e29b-41d4-a716-446655440000', 'user2@example.com');

7. Implementation Examples

JavaScript / Node.js

// Node.js (built-in since v14.17.0)
import { randomUUID } from 'crypto';
const uuid = randomUUID(); // v4

// Browser (modern browsers)
const uuid = crypto.randomUUID(); // v4

// Using uuid library (supports all versions)
import { v4 as uuidv4, v5 as uuidv5, v7 as uuidv7 } from 'uuid';

const id = uuidv4();  // Random
const id7 = uuidv7(); // Time-ordered (v7)

// v5 - deterministic from namespace + name
const DNS_NAMESPACE = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
const id5 = uuidv5('example.com', DNS_NAMESPACE);

// Validate UUID
function isValidUUID(str) {
    const regex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
    return regex.test(str);
}

Python

import uuid

# UUID v4 - Random
id_v4 = uuid.uuid4()
print(id_v4)  # e.g., f47ac10b-58cc-4372-a567-0e02b2c3d479

# UUID v1 - Timestamp + MAC (avoid for privacy)
id_v1 = uuid.uuid1()

# UUID v5 - Name-based (SHA-1)
id_v5 = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
# Always produces: cfbff0d1-9375-5685-968c-48ce8b15ae17

# UUID v7 (Python 3.12+)
# id_v7 = uuid.uuid7()

# Convert to/from string
str_uuid = str(id_v4)
parsed = uuid.UUID(str_uuid)

# Get bytes (for database storage)
uuid_bytes = id_v4.bytes  # 16 bytes

Java

import java.util.UUID;

public class UuidExample {
    public static void main(String[] args) {
        // UUID v4 - Random
        UUID uuid = UUID.randomUUID();
        System.out.println(uuid);
        
        // UUID v3/v5 - Name-based
        UUID namespace = UUID.fromString("6ba7b810-9dad-11d1-80b4-00c04fd430c8");
        UUID nameUuid = UUID.nameUUIDFromBytes("example.com".getBytes());
        
        // Parse from string
        UUID parsed = UUID.fromString("550e8400-e29b-41d4-a716-446655440000");
        
        // Get version
        int version = uuid.version(); // 4
        
        // Convert to bytes (for database)
        long msb = uuid.getMostSignificantBits();
        long lsb = uuid.getLeastSignificantBits();
    }
}

Go

package main

import (
    "fmt"
    "github.com/google/uuid"
)

func main() {
    // UUID v4
    id := uuid.New()
    fmt.Println(id) // e.g., 6ba7b810-9dad-11d1-80b4-00c04fd430c8
    
    // UUID v7 (time-ordered)
    id7, _ := uuid.NewV7()
    fmt.Println(id7)
    
    // Parse from string
    parsed, _ := uuid.Parse("550e8400-e29b-41d4-a716-446655440000")
    
    // Check version
    fmt.Println(parsed.Version()) // 1, 4, 7, etc.
}

PHP

<?php
// Using ramsey/uuid library
use Ramsey\Uuid\Uuid;

// UUID v4 - Random
$uuid = Uuid::uuid4();
echo $uuid->toString(); // e.g., f47ac10b-58cc-4372-a567-0e02b2c3d479

// UUID v7 - Time-ordered
$uuid7 = Uuid::uuid7();

// UUID v5 - Name-based
$uuid5 = Uuid::uuid5(Uuid::NAMESPACE_DNS, 'example.com');

// Parse and validate
$parsed = Uuid::fromString('550e8400-e29b-41d4-a716-446655440000');
$isValid = Uuid::isValid($someString);

// Get bytes for database
$bytes = $uuid->getBytes(); // 16 bytes
?>

8. UUID Alternatives

ULID Example:

// ULID format: 01ARZ3NDEKTSV4RRFFQ69G5FAV
// 48-bit timestamp + 80-bit random
// Lexicographically sortable, URL-safe

import { ulid } from 'ulid';
const id = ulid(); // 01ARZ3NDEKTSV4RRFFQ69G5FAV

nanoid Example:

// nanoid: V1StGXR8_Z5jdHi6B-myT
// Smaller, faster, URL-safe

import { nanoid } from 'nanoid';
const id = nanoid(); // V1StGXR8_Z5jdHi6B-myT

9. Best Practices

10. Frequently Asked Questions