What is a UUID and When Should You Use One?

A UUID (Universally Unique Identifier) is a 128-bit value used to uniquely identify resources in software systems. UUIDs are designed to be globally unique without requiring a central authority to issue them. You have probably seen them in URLs, database records, or API responses. They look like this: 550e8400-e29b-41d4-a716-446655440000.

The Structure of a UUID

A UUID consists of 32 hexadecimal digits displayed in five groups separated by hyphens, following the pattern 8-4-4-4-12. Despite containing hyphens, the canonical representation is always 36 characters long. The 128 bits give a total of 2^128 (about 3.4 x 10^38) possible values, which is an astronomically large number. The probability of generating two identical UUIDs is so small that it is practically zero.

UUID Versions

There are several UUID versions, each with a different generation strategy:

• UUID v1 is based on the current timestamp and the MAC address of the machine. It is time-ordered but leaks hardware information, which makes it unsuitable for security-sensitive contexts.
• UUID v4 is generated from random or pseudo-random numbers. It is the most widely used version because it is simple, fast, and does not leak any information. Most modern UUID libraries default to v4.
• UUID v5 is generated by hashing a namespace and a name using SHA-1. Given the same inputs, it always produces the same UUID. This is useful for creating deterministic identifiers from known data.
• UUID v7 is a newer format (RFC 9562) that combines a Unix timestamp with random bits. It is time-ordered like v1 but without the MAC address. v7 is gaining popularity for database primary keys because the time ordering improves index performance.

UUID vs Auto-Increment IDs

The classic alternative to UUIDs is sequential auto-increment integers (1, 2, 3...). Each approach has trade-offs:

• UUIDs can be generated anywhere (client, server, multiple databases) without coordination. They do not reveal how many records exist or when they were created (except v1/v7). They are harder to guess, which adds a layer of security for public-facing IDs.
• Auto-increment IDs are smaller (4 or 8 bytes vs 16 bytes), human-readable, and naturally ordered. They are faster to index in most databases. However, they require a single source of truth (usually the database) and expose information about your data volume.

A common pattern is to use auto-increment IDs internally for database efficiency and UUIDs as public-facing identifiers in APIs and URLs.

When to Use UUIDs

UUIDs are the right choice when you need identifiers that can be generated independently across distributed systems, when you want to avoid exposing sequential IDs in public APIs, when you need to merge data from multiple sources without ID conflicts, or when you generate IDs on the client side before sending data to the server.

Generating UUIDs in Code

Most languages have built-in or standard library support for UUID generation:

• JavaScript: crypto.randomUUID() is built into all modern browsers and Node.js 19+.
• Python: import uuid; uuid.uuid4()
• Go: github.com/google/uuid package
• PostgreSQL: gen_random_uuid() function

Common Pitfalls

• Do not use UUIDs as the clustered primary key in databases like MySQL/InnoDB without understanding the performance implications. Random v4 UUIDs cause index fragmentation. Use v7 or store UUIDs as BINARY(16) instead of VARCHAR(36).
• Do not treat UUIDs as secrets. While they are hard to guess, they are not cryptographic tokens. Use proper secrets for authentication.
• Be consistent with formatting. Always store and compare UUIDs in lowercase to avoid case-sensitivity issues.