Universally Unique Identifiers (UUIDs), also known as Globally Unique Identifiers (GUIDs), are 128-bit identifiers designed to provide a standardized way of generating unique values across distributed systems. For Python developers working with databases like PostgreSQL, understanding UUIDs is crucial for effective data management and system design.

UUIDs were originally defined by the Open Software Foundation (OSF) as part of the Distributed Computing Environment (DCE). They have since been standardized by the Internet Engineering Task Force (IETF) in RFC 4122.

The anatomy of a UUID

A UUID is typically represented as a 32-character hexadecimal string, divided into five groups separated by hyphens. For example:


The structure is as follows:

  • 8 characters (4 bytes): time_low
  • 4 characters (2 bytes): time_mid
  • 4 characters (2 bytes): time_hi_and_version
  • 4 characters (2 bytes): clock_seq_hi_and_reserved and clock_seq_low
  • 12 characters (6 bytes): node

This format results in 2^128 (approximately 3.4 x 10^38) possible unique values, making collisions extremely unlikely. To put this in perspective, you would need to generate 1 billion UUIDs every second for about 85 years to have a 50% probability of a single collision.

Understand UUIDs

UUID versions

There are several versions of UUIDs, each with different generation methods:

  1. Version 1: Time-based
    • Uses the current timestamp and MAC address of the computer
    • Provides uniqueness across space and time
    • Potential privacy concerns due to MAC address usage
  2. Version 2: DCE Security
    • Similar to version 1, but includes a local domain identifier
    • Rarely used in practice
  3. Version 3: Name-based (MD5 hash)
    • Generates a UUID based on a namespace identifier and a name
    • Uses MD5 hashing
    • Deterministic: same name and namespace always produce the same UUID
  4. Version 4: Random
    • Generates a UUID using random or pseudo-random numbers
    • Most commonly used due to its simplicity and lack of reliance on system-specific information
    • Provides strong uniqueness guarantees
  5. Version 5: Name-based (SHA-1 hash)
    • Similar to version 3, but uses SHA-1 hashing instead of MD5
    • Provides better collision resistance than version 3

Importance of UUIDs in software development

UUIDs offer several advantages in software development:

  1. Uniqueness across systems: UUIDs can be generated independently on different machines without coordination, maintaining uniqueness. This is particularly useful in distributed systems or when merging data from multiple sources.
  2. Scalability: In large-scale distributed systems, centralized ID generation can become a bottleneck. UUIDs allow for decentralized ID generation, improving system scalability.
  3. Privacy: Unlike sequential IDs, UUIDs don’t reveal information about the order or number of records. This can be important for security and data protection.
  4. Merge-friendly: When combining datasets from different sources, UUIDs minimize the risk of ID conflicts.
  5. Consistency across database shards: In sharded database architectures, UUIDs provide a consistent way to generate unique identifiers across all shards.
  6. Reduced chance of ID exhaustion: With 128 bits, the chance of running out of unique identifiers is virtually non-existent, unlike with auto-incrementing integers.
  7. Flexibility in data synchronization: UUIDs facilitate easier data synchronization between offline and online systems, as IDs can be generated without immediate database access.

Implementing UUIDs in Python

Python provides built-in support for UUIDs through the uuid module. Here’s a detailed look at generating and working with UUIDs in Python:

import uuid

# Generate a random UUID (version 4)
random_uuid = uuid.uuid4()
print(f"Random UUID: {random_uuid}")
print(f"UUID version: {random_uuid.version}")

# Generate a UUID from a string (version 5)
namespace = uuid.NAMESPACE_DNS
name = "example.com"
uuid_v5 = uuid.uuid5(namespace, name)
print(f"Version 5 UUID: {uuid_v5}")
print(f"UUID version: {uuid_v5.version}")

# Generate a time-based UUID (version 1)
time_uuid = uuid.uuid1()
print(f"Time-based UUID: {time_uuid}")
print(f"UUID version: {time_uuid.version}")

# Convert UUID to string and back
uuid_str = str(random_uuid)
uuid_from_str = uuid.UUID(uuid_str)
print(f"UUID from string: {uuid_from_str}")

# Access UUID fields
print(f"UUID fields: time_low={random_uuid.time_low}, node={random_uuid.node}")

# Check UUID equality
print(f"UUIDs equal: {random_uuid == uuid_from_str}")

# Generate a UUID with a specific version and variant
custom_uuid = uuid.UUID('12345678-1234-5678-1234-567812345678')
print(f"Custom UUID: {custom_uuid}")
print(f"Version: {custom_uuid.version}, Variant: {custom_uuid.variant}")

This code demonstrates various ways to generate and work with UUIDs in Python, including creating different versions, converting between UUID objects and strings, accessing UUID fields, and comparing UUIDs.

Using UUIDs with PostgreSQL and Python

PostgreSQL has native support for UUIDs. Here’s a detailed guide on how to use them with Python and psycopg2:

Enable the UUID extension in PostgreSQL:


Create a table with a UUID column:

    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    username VARCHAR(50) NOT NULL,

Insert and query data using Python:

import psycopg2
import uuid
from psycopg2.extras import DictCursor

# Database connection parameters
db_params = {
    "dbname": "your_db",
    "user": "your_user",
    "password": "your_password",
    "host": "localhost",
    "port": "5432"

def insert_user(username, email):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor() as cur:
            user_id = uuid.uuid4()
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s) RETURNING id",
                (user_id, username, email)
            inserted_id = cur.fetchone()[0]
    return inserted_id

def get_user(user_id):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor(cursor_factory=DictCursor) as cur:
            cur.execute("SELECT * FROM users WHERE id = %s", (user_id,))
            return cur.fetchone()

# Insert a new user
new_user_id = insert_user("john_doe", "[email protected]")
print(f"Inserted user with ID: {new_user_id}")

# Retrieve the user
user = get_user(new_user_id)
print(f"Retrieved user: {dict(user)}")

This example demonstrates how to insert a new user with a UUID primary key and then retrieve that user using the UUID. It uses a connection pool for better performance and resource management.

Performance considerations

While UUIDs offer many benefits, they come with some performance trade-offs:

  1. Storage: UUIDs require 128 bits of storage, compared to 32 or 64 bits for integer IDs. This increased size can impact storage requirements and memory usage.
  2. Indexing: UUID indexes are larger and potentially slower than integer indexes. This can affect query performance, especially for large tables.
  3. Insertion: Random UUIDs can lead to index fragmentation in B-tree indexes, which are commonly used in databases. This fragmentation can slow down insertions and queries over time.
  4. Sorting: UUIDs are not naturally sortable in a meaningful way (except for time-based versions), which can impact the performance of ORDER BY operations.

To mitigate these issues:

  1. Use UUID version 1 or custom time-based UUIDs for better database performance. The timestamp component allows for some natural ordering.
  2. Consider using BRIN (Block Range INdex) indexes instead of B-tree indexes for UUID columns in PostgreSQL. BRIN indexes are smaller and can be more efficient for UUID columns, especially in tables where UUIDs are inserted in a roughly sequential order.
  3. If using version 4 (random) UUIDs, consider periodically rebuilding indexes to combat fragmentation.
  4. For sorting, consider adding a separate timestamp column if time-based sorting is needed.

Example of creating a BRIN index in PostgreSQL:


UUID collisions and uniqueness guarantees

UUID collisions

While UUIDs are designed to be unique, it’s important to understand the probability of collisions:

  1. For version 4 (random) UUIDs, the probability of a collision is extremely low. You’d need to generate about 2^61 UUIDs to have a 50% chance of a single collision.
  2. Version 1 and 2 UUIDs, which use timestamps and MAC addresses, have even stronger uniqueness guarantees, but they can pose privacy concerns.
  3. Version 3 and 5 UUIDs are deterministic, so uniqueness depends on the uniqueness of the input namespace and name.

To further reduce the risk of collisions in critical systems, you can:

  1. Use a combination of timestamp and random data to create custom UUIDs.
  2. Implement a check-and-retry mechanism when inserting UUIDs into a database.

Example of a collision-resistant UUID insertion:

def insert_with_retry(cur, max_attempts=5):
    for attempt in range(max_attempts):
            user_id = uuid.uuid4()
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s)",
                (user_id, username, email)
            return user_id
        except psycopg2.errors.UniqueViolation:
            if attempt == max_attempts - 1:
    raise Exception("Failed to insert after maximum attempts")

This function will retry the insertion with a new UUID if a collision occurs, up to a maximum number of attempts.

Alternatives to UUIDs

While UUIDs are versatile, there are situations where alternatives might be more appropriate:

1. Auto-incrementing Integers


  • Simple and widely supported
  • Efficient for indexing and joining
  • Minimal storage requirements


  • Not suitable for distributed systems
  • Reveals information about record count and order
  • Risk of running out of values for very large datasets

Implementation in PostgreSQL:

    username VARCHAR(50) NOT NULL

2. NanoID

NanoID is a compact, URL-friendly unique string ID generator.


  • Shorter than UUIDs (21 characters by default)
  • Customizable alphabet and length
  • Faster generation than UUIDs
  • URL-friendly by default


  • Less widespread adoption compared to UUIDs
  • Not natively supported in databases

Python implementation:

from nanoid import generate

def create_user(username, email):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor() as cur:
            user_id = generate()
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s) RETURNING id",
                (user_id, username, email)
            return cur.fetchone()[0]

# Usage
new_user_id = create_user("jane_doe", "[email protected]")
print(f"Created user with NanoID: {new_user_id}")

3. ULID (Universally Unique Lexicographically Sortable Identifier)

ULIDs are 128-bit identifiers that combine timestamp and randomness.


  • Lexicographically sortable
  • Timestamp component allows for time-based sorting
  • As unique as UUIDs
  • Compact representation (26 characters)


  • Less widespread adoption
  • Not natively supported in many databases

Python implementation using the ulid-py library:

from ulid import ULID
import psycopg2

def create_user_ulid(username, email):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor() as cur:
            user_id = ULID()
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s) RETURNING id",
                (str(user_id), username, email)
            return cur.fetchone()[0]

# Usage
new_user_id = create_user_ulid("alice_wonder", "[email protected]")
print(f"Created user with ULID: {new_user_id}")

4. Snowflake IDs

Snowflake IDs, popularized by Twitter, are 64-bit IDs composed of a timestamp, worker number, and sequence number.


  • Smaller than UUIDs (64 bits)
  • Time-sortable
  • Suitable for high-concurrency distributed systems


  • Requires careful implementation to avoid collisions
  • Not as universally unique as UUIDs across different systems
  • Requires coordination for worker ID assignment

Python implementation (simplified version):

import time
import threading

class SnowflakeGenerator:
    def __init__(self, datacenter_id, worker_id):
        self.datacenter_id = datacenter_id
        self.worker_id = worker_id
        self.sequence = 0
        self.last_timestamp = -1
        self.lock = threading.Lock()

    def next_id(self):
        with self.lock:
            timestamp = int(time.time() * 1000)
            if timestamp < self.last_timestamp:
                raise ValueError("Clock moved backwards")
            if timestamp == self.last_timestamp:
                self.sequence = (self.sequence + 1) & 4095
                if self.sequence == 0:
                    timestamp = self._wait_next_millis(self.last_timestamp)
                self.sequence = 0
            self.last_timestamp = timestamp
            return ((timestamp & 0x1FFFFFFFFFF) << 22) | \
                   (self.datacenter_id << 17) | \
                   (self.worker_id << 12) | \

    def _wait_next_millis(self, last_timestamp):
        timestamp = int(time.time() * 1000)
        while timestamp <= last_timestamp:
            timestamp = int(time.time() * 1000)
        return timestamp

# Usage
snowflake = SnowflakeGenerator(datacenter_id=1, worker_id=1)

def create_user_snowflake(username, email):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor() as cur:
            user_id = snowflake.next_id()
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s) RETURNING id",
                (user_id, username, email)
            return cur.fetchone()[0]

# Create a user with a Snowflake ID
new_user_id = create_user_snowflake("bob_builder", "[email protected]")
print(f"Created user with Snowflake ID: {new_user_id}")

Choosing the right identifier

When deciding between UUIDs and alternatives, consider:

1. System requirements:

  • Distributed vs. centralized architecture
  • Scalability needs
  • Data synchronization requirements

2. Performance impact:

  • Storage requirements
  • Indexing efficiency
  • Query performance, especially for large datasets
  • Insertion speed and index fragmentation

3. Data sensitivity:

  • Need for obfuscation of record order or count
  • Privacy concerns related to system information leakage

4. Compatibility:

  • Required support in databases, libraries, and frameworks
  • Ease of integration with existing systems

5. Sorting requirements:

  • Need for natural time-based sorting
  • Importance of lexicographical ordering

6. Collision resistance:

  • Tolerance for potential ID collisions
  • Importance of guaranteed uniqueness across systems

7. ID length and format:

  • URL-friendliness
  • Human readability
  • Storage efficiency

Implementing custom ID solutions

Sometimes, a custom ID solution might be the best fit for your specific needs. Here’s an example of a hybrid approach that combines timestamp and random components:

import time
import random
import base64

def generate_custom_id():
    timestamp = int(time.time() * 1000)
    random_component = random.getrandbits(32)
    combined = (timestamp << 32) | random_component
    return base64.urlsafe_b64encode(combined.to_bytes(12, 'big')).decode('utf-8').rstrip('=')

# Usage
custom_id = generate_custom_id()
print(f"Custom ID: {custom_id}")

This custom ID generator creates a 12-byte (96-bit) identifier that includes a timestamp and a random component, encoded in URL-safe base64. It provides a good balance between uniqueness, sortability, and compact representation.

Best practices for using UUIDs in Python and PostgreSQL

  1. Use appropriate UUID versions:
    • Version 4 for general use cases where randomness is preferred
    • Version 1 or custom time-based UUIDs for better database performance
  2. Index optimization:
    • Use BRIN indexes for UUID columns in large tables
    • Regularly maintain and rebuild B-tree indexes if used
  3. Storage considerations:
    • Use the PostgreSQL UUID type for efficient storage
    • Consider using COMPRESS or specific storage engines for large UUID columns
  4. Bulk operations:
    • Use batch inserts for better performance when adding multiple records with UUIDs
  5. Application-level caching:
    • Implement caching strategies to reduce database lookups for frequently accessed UUIDs
  6. Error handling:
    • Implement robust error handling for potential (though unlikely) UUID collisions

Premium content from UnfoldAI (ebooks, cheat sheets, tutorials)

Example of bulk insert with UUIDs:

import psycopg2
import uuid

def bulk_insert_users(users):
    with psycopg2.connect(**db_params) as conn:
        with conn.cursor() as cur:
            values = [(uuid.uuid4(), user['username'], user['email']) for user in users]
                "INSERT INTO users (id, username, email) VALUES (%s, %s, %s)",
    return len(values)

# Usage
users_to_insert = [
    {'username': 'user1', 'email': '[email protected]'},
    {'username': 'user2', 'email': '[email protected]'},
    # ... more users ...
inserted_count = bulk_insert_users(users_to_insert)
print(f"Inserted {inserted_count} users")

Future trends and considerations

As data management evolves, new trends and considerations for unique identifiers emerge:

  1. Decentralized identifiers (DIDs): These provide a new approach to creating globally unique identifiers without a centralized authority.
  2. Quantum-resistant identifiers: As quantum computing advances, there may be a need for new types of identifiers that resist quantum attacks.
  3. Privacy-enhancing identifiers: Future identifier systems may incorporate advanced privacy features, such as zero-knowledge proofs.
  4. Blockchain-based identifiers: Distributed ledger technologies offer new possibilities for creating and managing unique identifiers.
  5. Edge computing considerations: As edge computing grows, identifier systems that work well in distributed, occasionally-connected environments will become more important.


UUIDs provide a robust solution for generating unique identifiers in distributed systems. For Python developers working with PostgreSQL, they offer a standardized, well-supported option with strong uniqueness guarantees. However, it’s essential to consider the specific needs of your application, including performance requirements, system architecture, and scalability concerns, when choosing between UUIDs and alternative identification schemes.

By understanding the strengths and limitations of UUIDs and their alternatives, you can make informed decisions that balance uniqueness, performance, and scalability in your Python applications. Whether you choose UUIDs, one of the alternatives discussed, or a custom solution, the key is to align your choice with your specific use case and system requirements.

Remember that the field of unique identifiers is continually evolving, and staying informed about new developments and best practices will help you make the best choices for your projects over time. Regular performance testing and monitoring of your chosen identifier system in production will also help ensure it continues to meet your needs as your application grows and evolves.

Last Update: 05/07/2024