UUID v4 explained: a developer's guide to unique identifiers

UUIDs are everywhere in modern software. Database primary keys, session tokens, file names, distributed messages, idempotency keys, and test fixtures all lean on them. Among the seven official UUID versions, version 4 is the one most developers actually use. This article explains why, walks through how UUID v4 works, compares it to traditional auto-increment IDs, and shows when each is the better choice.

What is a UUID?

UUID stands for Universally Unique Identifier. It is a 128-bit number, written as 32 hexadecimal digits split into 5 groups separated by hyphens, like 550e8400-e29b-41d4-a716-446655440000. The point of a UUID is to identify something uniquely without needing a central authority to hand out IDs. Two computers anywhere on the planet can each generate a UUID at the same time and the chance of them matching is so small it is effectively zero.

The seven UUID versions

The UUID standard (RFC 4122 and its successors) defines several versions, each with different trade-offs. You will encounter these in real code:

• v1: time-based, includes a timestamp and the MAC address of the generating machine. Predictable, can leak network identity.
• v3 / v5: hash-based. Same input always produces the same UUID. Useful when you need deterministic IDs derived from some source data.
• v4: fully random. The most common version. What this article focuses on.
• v6: a re-ordered v1 that sorts naturally by time. Useful as a database key when you need time-ordering plus uniqueness.
• v7: time-based with random tail. Modern alternative to v1, increasingly recommended for database primary keys.

How UUID v4 is generated

UUID v4 is constructed almost entirely from random data. Out of the 128 bits, 6 are reserved to mark the UUID as version 4 and identify the variant. The remaining 122 bits come from a cryptographically secure random number generator. That is the whole algorithm.

With 122 bits of randomness, the chance of collision is astronomically small. To have a 50 percent chance of generating a single duplicate, you would need to generate one billion UUIDs every second for about 85 years. For practical purposes, UUID v4 values can be treated as unique forever.

UUID v4 vs auto-increment IDs

When auto-increment wins

• Single-database systems with no merging concerns
• When index performance is critical and you need natural insertion order
• Smaller storage footprint matters (16 bytes per row adds up over millions)
• Human-readable IDs are useful (invoice numbers, order numbers)

When UUID v4 wins

• Distributed systems where multiple nodes generate IDs
• Mobile or offline-first apps where the client generates IDs before sync
• When you do not want to leak business metrics (user count, order count)
• When you need to merge data from multiple sources without ID collisions
• Public-facing IDs where guessability is a security concern

Common pitfalls and tips

Storing UUIDs efficiently

A UUID is 16 bytes of binary data. Stored as a hex string with hyphens, it is 36 bytes. PostgreSQL has a native uuid type that stores it as 16 bytes. MySQL gives you BINARY(16) if you want compactness or CHAR(36) if you prefer queryable hex. Pick the binary form for production tables; you will pay 30 to 50 percent extra disk for the text form.

Index performance

UUID v4 values are random, which is bad for B-tree indexes because every insert lands in a random spot. This causes index fragmentation and worse cache locality compared to sequential integers. For huge tables, consider UUID v7 or ULID instead, both of which are time-ordered while still being collision-safe.

Do not use UUIDs as session tokens

UUID v4 is random but not specifically designed for session tokens. Use a longer cryptographically random string (32 bytes Base64 encoded) for session IDs, API keys, and anything where guessability matters. UUIDs are fine but slightly weaker than purpose-built tokens.

Beware UUID v1 in public-facing IDs

UUID v1 includes the MAC address of the machine that generated it. Exposing v1 UUIDs to the public can leak information about your infrastructure. If you must generate v1, use the random node ID variant or just use v4 instead.

Real-world use cases

Idempotency keys

When making API requests that change state (charging a card, sending an email), include a UUID as an idempotency key. If the client retries the request, the server sees the same key and returns the original result instead of repeating the action. Stripe, Square, and most payment APIs work this way.

File names

When users upload files, save them with UUID names and store the original filename as metadata. This avoids name collisions, prevents path injection attacks, and works well with object storage like S3 or R2.

Distributed event IDs

In event-driven architectures, every event needs a unique ID so consumers can deduplicate retries. UUID v4 generated at the producer is the standard choice. Logging the UUID makes end-to-end tracing across services possible.

Test data

When seeding development databases or writing tests, UUIDs make records identifiable without coupling to actual order or count. A test that creates a user with email test-{uuid}@example.com will not collide with other parallel tests.

Generating UUIDs

Modern browsers and runtimes have built-in UUID v4 generators. In JavaScript, crypto.randomUUID() is available natively. In Node.js, require('crypto').randomUUID(). In Python, uuid.uuid4(). In Go, the google/uuid package. Every major language has a standard or near-standard library.

Summary

UUID v4 is a 128-bit random identifier. It is unique enough for any practical purpose, can be generated anywhere without coordination, and reveals no information about the system that produced it. Use it for distributed systems, client-side ID generation, public IDs, and anything that needs to be unique across machines or merge cleanly across databases. For new projects in 2026, look at UUID v7 if you want time-ordering with a similar uniqueness guarantee.