What Is a UUID? A Complete Guide

Modern applications need identifiers for users, orders, products, sessions, transactions, API resources, database records, and distributed-system objects. However, sequential IDs can become difficult to manage in distributed systems, while UUIDs provide a standardized large identifier space suitable for generating identifiers independently.

A UUID is a standardized identifier designed to provide practical uniqueness across systems without requiring a central ID-generation authority.

What Is a UUID?

A Universally Unique Identifier (UUID) is a 128-bit number used to identify information in computer systems. UUIDs were created to solve the problem of generating identifiers in distributed environments—like multiple servers, microservices, offline clients, databases, and APIs—where coordinating a centralized sequence (like auto-incrementing database IDs) becomes a bottleneck or a single point of failure.

Because the UUID space is so massive, different systems can independently generate UUIDs without communicating with one another, yet still be extremely confident that their generated identifiers will not clash.

What Does UUID Stand For?

Let's break down each word in the acronym:

• Universally: Designed to work across systems, architectures, and environments universally without overlap.
• Unique: Designed to make accidental collisions extremely unlikely (though uniqueness is not mathematically guaranteed).
• Identifier: Its entire purpose is to uniquely identify something—a record, a file, a user, etc.

What Does a UUID Look Like?

A UUID in its canonical text representation looks like this:

This familiar representation contains 32 hexadecimal digits + 4 hyphens. It is structured into five groups separated by hyphens:

• 8 hexadecimal characters
• 4 hexadecimal characters
• 4 hexadecimal characters
• 4 hexadecimal characters
• 12 hexadecimal characters

Underneath this 36-character string representation, the data is just a 128-bit number.

UUID Structure Explained

The layout of a UUID maps to different bit lengths for each block:

Specific bits within these groups define the UUID version and variant. These reserved bits tell parsers how the UUID was generated. However, it's important to remember that not every UUID version uses the remaining bits for the same purpose—some use them for random data, others for timestamps, and others for hardware MAC addresses.

How UUIDs Work

UUID generation depends entirely on the version being used. Depending on the version, a UUID might be generated using:

• Random generation: Relying on cryptographically secure random number generators.
• Time-based generation: Combining a system timestamp with hardware addresses.
• Name-based generation: Using hashing algorithms (like MD5 or SHA-1) against a specific namespace and name.
• Time-ordered generation: Fusing timestamps with randomness to create sortable IDs.

UUID Versions Explained

There are multiple versions of UUIDs, standardized by organizations like the IETF (RFC 4122 and newer RFC 9562). Here is a comprehensive overview:

UUID v1

UUID version 1 is a time-based generation method. It constructs the identifier using the current timestamp and node information, typically the MAC address of the machine generating it.

While useful for ensuring no two machines generate the same UUID at the same time, exposing the MAC address raises privacy and security considerations. Furthermore, the timestamp in v1 is not optimally arranged for database sorting, making it less ideal for modern data storage. Developers should carefully evaluate v1 before choosing it for new systems.

UUID v3

UUID version 3 is a name-based generation method. It uses the MD5 hashing algorithm to combine a predefined namespace and a specific name (like a URL or a string) to produce a deterministic output.

Deterministic IDs are useful when you need to repeatedly generate the same UUID from the same input across different systems without communicating. However, MD5 is considered cryptographically weak today, leading to the creation of UUID v5.

UUID v4 Explained

UUID version 4 is the most popular and widely used version. It relies entirely on random or pseudorandom generation. Out of the 128 bits, 122 bits are purely random data, while the remaining bits designate the UUID version and variant.

In the pattern above:

• 4 represents the UUID version.
• y represents the variant-related bits (typically 8, 9, a, or b in hexadecimal).
• The x characters represent random hexadecimal digits.

UUID v4 is the default choice for general-purpose identifiers. It is extremely easy to generate, requires no coordination between servers, and the probability of collision is so small it can be practically ignored for most applications.

UUID v5

Like v3, UUID version 5 is a name-based, deterministic generation method that requires a namespace and a name. However, UUID v5 uses the SHA-1 hashing algorithm instead of MD5. While SHA-1 is also considered weak for high-security cryptographic signatures today, it is significantly better than MD5 and remains the standard for generating deterministic UUIDs.

UUID v6

UUID version 6 was created to solve the database sorting problems of UUID v1. By reordering the timestamp bits, UUID v6 ensures that newly generated IDs have better lexical and time-ordering characteristics. This makes them much more efficient for database indexing. It serves primarily as a bridge for legacy systems that required v1-like MAC address inclusion but needed better database performance.

UUID v7 Explained

UUID version 7 has gained massive attention for modern applications and distributed systems. It combines a 48-bit Unix timestamp with 74 bits of randomness.

Because a UUID v7 begins with a timestamp, it is naturally time-ordered. When inserted into a database, v7 UUIDs are appended sequentially rather than scattered randomly across the database index (B-tree). This resolves one of the biggest complaints against UUID v4: index fragmentation and poor write performance at scale.

UUID v4 vs UUID v7

The choice between v4 and v7 is one of the most common decisions developers face today. Let's compare them:

Neither version is universally superior. If you want maximum unpredictability and do not care about database indexing (e.g., generating an API key or session token), v4 is perfect. If you are generating millions of rows for a relational database primary key, v7 provides superior storage performance.

UUID Collision Probability

A collision occurs when two identical UUIDs are generated. Developers often worry about this when they learn that UUIDs are not mathematically guaranteed to be unique.

Because of the birthday paradox, as more UUIDs are generated, the collision probability increases. However, the probability remains extraordinarily small for realistic application volumes. To reach a 50% chance of a single collision, you would need to generate 1 billion UUIDs per second for 85 years.

Are UUIDs Really Unique?

This brings us to a critical distinction:

• Mathematical guarantee: No. Because the number of possible UUIDs is finite, and generation relies on random probability, there is no strict mathematical guarantee of absolute uniqueness.
• Practical uniqueness: Yes. The probability of a collision using a cryptographically secure random number generator is so vanishingly small that developers treat UUIDs as practically unique.

UUID vs GUID

You will often hear the terms UUID and GUID used interchangeably. Here is how they compare:

In modern usage, the terms are treated as effectively interchangeable, though terminology and specific byte-order implementation details can sometimes vary.

UUID vs Auto-Increment IDs

When designing a database, one of the biggest debates is whether to use sequential Auto-Increment IDs (like 1, 2, 3) or UUIDs for primary keys.

Remember: While UUIDs provide enumeration resistance (preventing users from guessing the next ID), they are not automatically a security control.

UUIDs in Databases

UUIDs are heavily used as primary and foreign keys in databases like PostgreSQL, MySQL, SQL Server, and SQLite. However, standard UUID v4 presents a challenge for B-tree indexes. Because v4 is entirely random, every insert occurs at a random location in the index, causing massive page fragmentation and slowing down write performance at high scale.

This is why time-ordered UUIDs (like v7) are highly recommended for database indexing. They provide the decentralized generation benefits of UUIDs while retaining the sequential insert performance of auto-incrementing IDs. Furthermore, always ensure you store UUIDs efficiently—preferably as 16-byte binary data rather than 36-character strings to save storage and memory.

UUIDs in APIs

In public-facing REST or GraphQL APIs, UUIDs are the gold standard for resource identification.

Using UUIDs in APIs prevents malicious users from easily scraping your entire database by just incrementing a number. They also decouple your API's public interface from your internal database logic. However, UUIDs should never be treated as authentication credentials or secrets.

UUIDs in Distributed Systems

In microservices, event-driven systems, and distributed databases, independent services must generate identifiers without coordinating every ID assignment. A mobile app offline-first architecture can generate a UUID locally, save a record, and later sync with the central server without fear of a primary key collision. They are also widely used as message IDs or correlation IDs to trace requests across complex service networks.

UUID Security Considerations

There is a significant misconception regarding UUIDs and security. Developers must clearly understand:

• UUID ≠ encryption
• UUID ≠ hashing
• UUID ≠ authentication
• UUID ≠ authorization
• UUID ≠ secret token

Random UUIDs (v4) are hard to guess, making them useful identifiers, but sensitive operations should rely on proper authentication and authorization mechanisms. Do not assume that just because a user doesn't know the UUID, the resource is secure.

Are UUIDs Safe to Expose in URLs?

Yes, UUIDs are commonly exposed in URLs (e.g., /dashboard/projects/123e4567-e89b-12d3-a456-426614174000).

However, this is only safe if you enforce access controls. UUID obscurity is not access control. Authorization is still required to ensure the user requesting the URL actually has permissions to view or modify that specific resource. Remember that URLs are often stored in browser histories and server logs, so true secrets should never be placed in a URL.

Common UUID Mistakes

Avoid these frequent pitfalls when working with UUIDs:

1. Assuming UUIDs are mathematically unique: They are probabilistically unique.
2. Treating UUIDs as passwords: They provide identification, not authentication.
3. Using UUIDs as authorization: Obscurity is not a replacement for proper permission checks.
4. Choosing v4 without considering ordering requirements: Random IDs can fragment databases.
5. Ignoring database indexing implications: High-volume writes suffer with v4.
6. Using a weak random generator: Relying on Math.random() instead of crypto libraries for v4.
7. Storing UUIDs inefficiently: Storing them as 36-byte strings instead of 16-byte binaries in DBs.
8. Treating every UUID version as equivalent: They solve different problems.
9. Exposing UUIDs without access control: Assuming unguessable means secure.
10. Assuming UUIDs cannot be guessed: A poorly seeded random generator creates predictable UUIDs.
11. Ignoring UUID format validation: Accepting malformed UUID strings in APIs.
12. Generating IDs inconsistently across services: Mixing v4 and v7 without a clear strategy.

UUID Best Practices

• Choose the UUID version based on application requirements.
• Use a cryptographically appropriate random source when generating random UUIDs.
• Consider UUID v7 where time ordering benefits storage/indexing.
• Use UUID v4 for straightforward general-purpose random identifiers.
• Do not use UUIDs as secrets.
• Do not rely on UUIDs for authorization.
• Validate UUID input at application boundaries (e.g., API gateways).
• Consider database storage and indexing behavior before committing to a format.
• Keep UUID generation consistent across services.
• Document UUID version expectations in your API specifications.

How to Generate a UUID

Generating a UUID is simple in almost any modern programming language. Alternatively, developers can generate UUIDs instantly without writing code using our online utility.

JavaScript / TypeScript

// Native browser/Node.js support
const crypto = require('crypto');
const myUuid = crypto.randomUUID();
console.log(myUuid); 
// Output: "36b8f84d-df4e-4d49-b662-bcde71a8764f"

Python

import uuid

# Generate a random UUID v4
my_uuid = uuid.uuid4()
print(str(my_uuid))
# Output: "36b8f84d-df4e-4d49-b662-bcde71a8764f"

Java

import java.util.UUID;

// Generate a random UUID v4
UUID myUuid = UUID.randomUUID();
System.out.println(myUuid.toString());

C#

using System;

// Generate a random GUID (UUID v4)
Guid myUuid = Guid.NewGuid();
Console.WriteLine(myUuid.ToString());

Go

package main

import (
    "fmt"
    "github.com/google/uuid" // Requires external package
)

func main() {
    myUuid := uuid.New()
    fmt.Println(myUuid.String())
}

UUID Validation Example

If you need to validate that a string matches the UUID format, you can use a regular expression (Regex). Note that format validation does not prove the UUID exists in a database, that it was generated securely, or that it is authentic.

// Standard Regex for UUID v4 validation
const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;

console.log(uuidRegex.test("550e8400-e29b-41d4-a716-446655440000")); // true

Frequently Asked Questions