UUID v4 genereren in Python — uuid.uuid4() gids

Telkens wanneer ik een botsingsbestendige identifier nodig heb voor een databaserij, API-trace of sessietoken, is het antwoord UUID v4 genereren in Python — één regel, nul afhankelijkheden: uuid.uuid4(). De ingebouwde uuid module van Python gebruikt os.urandom() voor cryptografisch veilige willekeurigheid. Voor een snelle UUID zonder code te schrijven werkt de online UUID v4 generator direct. Deze gids behandelt de attributen van het UUID-object, bulkgeneratie, JSON-serialisatie, databaseopslag, validatie, uuid-utils (~10× snellere Rust-backed drop-in) en de vier meest voorkomende fouten — alles met Python 3.8+.

Wat is UUID v4?

Een UUID (Universally Unique Identifier) is een 128-bit label opgemaakt als 32 hexadecimale cijfers verdeeld in vijf groepen door koppeltekens: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Versie 4 is de meest gebruikte variant: 122 van die 128 bits zijn willekeurig gegenereerd, en de overige 6 bits coderen de versie (4) en variant (RFC 4122). Er is geen tijdstempel en geen hostidentificator — de identifier is volledig ondoorzichtig en privacy-veilig. De kans dat twee onafhankelijk gegenereerde v4 UUID's botsen is zo klein dat het voor praktische doeleinden nooit voorkomt, zelfs niet in gedistribueerde systemen die miljoenen ID's per seconde genereren.

event_id = "evt-" + str(random.randint(100000, 999999))  # fragile, not unique

event_id = str(uuid.uuid4())  # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

uuid.uuid4() — De standaardmanier om UUID v4 te genereren in Python

De uuid module maakt deel uit van Python's standaardbibliotheek. Het aanroepen van uuid.uuid4() geeft een uuid.UUID object terug met een volledige set attributen voor verschillende representaties. Converteren naar een string met str() geeft het canonieke koppelteken-formaat dat API's, databases en HTTP-headers verwachten.

import uuid

# Genereer een UUID v4
request_id = uuid.uuid4()

print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(type(request_id))     # <class 'uuid.UUID'>
print(request_id.version)   # 4

# Converteer naar string voor JSON / HTTP-headers
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (zonder koppeltekens)
print(request_id.bytes)     # b';...' (16 onbewerkte bytes)

Een veelvoorkomend praktijkpatroon is het koppelen van een UUID aan elk uitgaand API-verzoek zodat je logboeken kunt correleren over services heen. Hier is een minimale requests-sessiewrapper die een verse UUID in elke aanroep injecteert:

import uuid
import requests

def call_api(endpoint: str, payload: dict) -> dict:
    trace_id = str(uuid.uuid4())
    headers = {
        "X-Request-ID": trace_id,
        "Content-Type": "application/json",
    }
    response = requests.post(endpoint, json=payload, headers=headers, timeout=10)
    response.raise_for_status()
    return {"trace_id": trace_id, "data": response.json()}

# result["trace_id"] laat je het exacte verzoek terugvinden in alle servicelogboeken
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # bijv. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

Bij het bulkgenereren van UUID's — bijvoorbeeld het vooraf vullen van een batch databaserijen — is een lijstcomprehensie idiomatisch en leesbaar:

import uuid

# Genereer ID's voor 1000 telemetriegebeurtenissen
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # bijv. "a1c2e3f4-..."
print(event_ids[-1])  # elke keer een andere waarde

Heb je snel een UUID nodig zonder code te draaien? Gebruik de online UUID v4 generator om met één klik een verse waarde te kopiëren, of genereer er honderden tegelijk — handig voor het vullen van testdatabases of fixture-bestanden.

UUID-objectattributen en representaties

Het uuid.UUID object biedt meerdere representaties van dezelfde 128-bit waarde. De juiste keuze voor je opslaglaag voorkomt stille datacorruptie en verspilde bytes.

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  (36 tekens)
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      (32 tekens, zonder koppeltekens)
print(u.bytes)        # b';Š...'                       (16 bytes, big-endian)
print(u.bytes_le)     # b'Š...'                       (16 bytes, little-endian)
print(u.int)          # 78823... (128-bit integer)
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# Heen-en-terug: reconstrueer vanuit string
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (als u die waarde had)

Voor PostgreSQL met psycopg2 of asyncpg geef je het UUID object direct door — de driver regelt de toewijzing aan het native uuid kolomtype. Voor SQLite gebruik je str(u) (TEXT) of u.bytes (BLOB, 16 bytes vs 36 voor de string). Voor opslagefficiëntie op schaal is .bytes 55% kleiner dan de canonieke string.

UUID v4-strings valideren en parseren in Python

Telkens wanneer een UUID binnenkomt via gebruikersinvoer, een URL-padparameter of een upstream API, moet je deze valideren voordat je hem gebruikt als databasesleutel. De idiomatische aanpak is een constructiepoging met uuid.UUID() en het opvangen van ValueError. Je kunt ook afdwingen dat de inkomende waarde specifiek versie 4 is door .version te controleren.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Parseer en valideer een UUID v4-string.
    Gooit ValueError voor ongeldig formaat of verkeerde versie.
    """
    try:
        u = uuid.UUID(raw)
    except ValueError as exc:
        raise ValueError(f"Invalid UUID format: {raw!r}") from exc

    if u.version != 4:
        raise ValueError(f"Expected UUID v4, got v{u.version}: {raw!r}")

    return u

# Gebruik in een FastAPI / Flask route-handler
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # veilig om uid te gebruiken in een databasequery
    return {"order_id": str(uid), "status": "processing"}

UUID v4 in JSON-payloads en API-responses

De JSON-standaard heeft geen UUID-type — een UUID in JSON is altijd een string. Dat betekent dat je het uuid.UUID object naar een string moet converteren voordat je het doorgeeft aan json.dumps(). De schoonste aanpak is een aangepaste JSONEncoder subklasse zodat je nooit str() aanroepen door je codebase hoeft te verspreiden.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serialiseer UUID- en datetime-objecten in JSON-responses."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# Realistische API-response met geneste UUID's
api_response = {
    "request_id": uuid.uuid4(),
    "created_at": datetime(2026, 3, 14, 9, 41, 0),
    "order": {
        "id": uuid.uuid4(),
        "customer_id": uuid.uuid4(),
        "items": [
            {"product_id": uuid.uuid4(), "sku": "NVX-9000", "qty": 2},
        ],
    },
}

print(json.dumps(api_response, indent=2, cls=ApiEncoder))
# {
#   "request_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "created_at": "2026-03-14T09:41:00",
#   "order": {
#     "id": "a1c2e3f4-...",
#     ...
#   }
# }

Voor een eenmalige serialisatieaanroep is de default= hook eenvoudiger dan subklassen:

import json, uuid

event_id = uuid.uuid4()
payload = {"event_id": event_id, "action": "checkout"}

# Geef een callable door; wordt alleen aangeroepen voor typen die json niet kan verwerken
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Bij het ontvangen van een response van een externe API, parseer je UUID-strings terug naar objecten zodat je code de volledige attribuutset en typeveiligheid krijgt:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Haal een zending op en geef terug met getypeerde UUID-velden."""
    response = requests.get(
        f"https://api.logistics.example.com/v2/shipments/{shipment_id}",
        headers={"Accept": "application/json"},
        timeout=10,
    )
    response.raise_for_status()
    data = response.json()

    # Parseer de UUID-velden terug naar uuid.UUID-objecten
    try:
        data["id"] = uuid.UUID(data["id"])
        data["carrier_id"] = uuid.UUID(data["carrier_id"])
    except (KeyError, ValueError) as exc:
        raise RuntimeError(f"Malformed shipment response: {exc}") from exc

    return data

Om UUID-velden in een JSON-bestand op schijf bij te werken — bijvoorbeeld het roteren van een correlatie-ID in een configuratie- of seed-bestand — lees je, pas je aan en schrijf je atomair terug:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Vervang of voeg 'correlation_id' toe in een JSON-bestand. Geeft de nieuwe UUID terug."""
    try:
        with open(path) as f:
            data = json.load(f)
    except FileNotFoundError:
        data = {}
    except json.JSONDecodeError as exc:
        raise ValueError(f"Invalid JSON in {path!r}: {exc}") from exc

    new_id = str(uuid.uuid4())
    data["correlation_id"] = new_id

    with open(path, "w") as f:
        json.dump(data, f, indent=2)

    return new_id

Als je niet elke keer een script wilt draaien om een UUID uit een API-response te inspecteren, plak je hem direct in de UUID Decoder — die toont je de versie, variant en alle velden zonder code.

UUID v4 genereren via de commandoregel met Python

Python's uuid module biedt geen zelfstandige CLI-subcommando zoals python -m json.tool, maar een one-liner dekt hetzelfde gebruiksscenario. Deze zijn handig in shellscripts, CI-pipelines en wanneer je een wegwerpidentifier nodig hebt zonder een REPL te openen.

# Enkele UUID v4
python3 -c "import uuid; print(uuid.uuid4())"
# 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e

# Geen-koppeltekens (hex) formaat — handig voor bestandsnamen en omgevingsvariabelen
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Genereer 5 UUID's voor een batch seed-script
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Gebruik in een shellvariabele
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

Hoge-prestatie UUID v4 met uuid-utils

De uuid.uuid4() van de standaardbibliotheek is snel genoeg voor de meeste toepassingen — bij een paar microseconden per aanroep verwerkt het gemakkelijk duizenden ID's per seconde. Als je UUID's genereert op het kritieke pad van een high-throughput service (bulkinvoegingen, per-event telemetrie op schaal, of het genereren van verzoek-ID's onder zware belasting), uuid-utils is een drop-in vervanging backed door Rust die benchmarkt op ongeveer 10x de snelheid van de standaardbibliotheek.

pip install uuid-utils

# uuid_utils is een drop-in vervanging voor de stdlib uuid-module
import uuid_utils as uuid

# Dezelfde API als stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # canonieke string
print(request_id.hex)       # hex zonder koppeltekens
print(request_id.version)   # 4

# Ondersteunt ook v7 (tijdgeordend, ideaal voor DB-primaire sleutels)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # begint met huidig tijdstempelvoorvoegsel

UUID v4 in dataclasses en Pydantic-modellen

Python-dataclasses en Pydantic-modellen ondersteunen beide UUID-velden native. Het sleutelpatroon bij het gebruik van UUID als automatisch gegenereerde standaardwaarde is het doorgeven van de functieverwijzing, niet een aanroepresultaat — anders deelt elke instantie dezelfde UUID.

from dataclasses import dataclass, field
import uuid

@dataclass
class WorkerJob:
    job_id: uuid.UUID = field(default_factory=uuid.uuid4)
    worker_id: str = "worker-01"
    payload: dict = field(default_factory=dict)

job1 = WorkerJob(payload={"task": "resize_image", "src": "uploads/img_4932.png"})
job2 = WorkerJob(payload={"task": "send_email",   "to":  "ops@example.com"})

print(job1.job_id)  # uniek per instantie
print(job2.job_id)  # verschilt van job1.job_id
print(job1.job_id == job2.job_id)  # False

from pydantic import BaseModel, Field
import uuid

class OrderEvent(BaseModel):
    event_id: uuid.UUID = Field(default_factory=uuid.uuid4)
    order_id: uuid.UUID
    status: str
    amount_cents: int

event = OrderEvent(
    order_id=uuid.UUID("a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f"),
    status="payment_confirmed",
    amount_cents=4995,
)

print(event.model_dump_json(indent=2))
# {
#   "event_id": "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e",
#   "order_id": "a1c2e3f4-5b6d-4e7f-8c9d-0a1b2c3d4e5f",
#   "status": "payment_confirmed",
#   "amount_cents": 4995
# }
# Pydantic v2 serialiseert uuid.UUID automatisch als string

Veelgemaakte fouten bij het genereren van UUID v4 in Python

Ik heb alle vier deze patronen gezien in code-reviews en productie-incidenten — ze zijn makkelijk over het hoofd te zien omdat ze niet direct een fout gooien.

@dataclass
class Session:
    # FOUT: eenmalig geëvalueerd, alle instanties delen deze UUID
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # CORRECT: factory wordt per instantie aangeroepen
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Geeft False terug zelfs als waarden overeenkomen
if record["session_id"] == "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e":
    revoke_session(record)

target = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
if record["session_id"] == target:   # beide zijn uuid.UUID
    revoke_session(record)

# Of normaliseer alles naar strings op de grens:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Slaat op "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — zonder koppeltekens
payload = {"correlation_id": request_id.hex}

# Slaat op "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e" — standaardformaat
payload = {"correlation_id": str(request_id)}

import random, secrets

# Geen UUID — mislukt bij uuid.UUID()-validatie
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — totaal verkeerd

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# Geldige UUID v4, cryptografisch veilig

UUID-generatiemethoden in Python — Snelle vergelijking

Alle onderstaande methoden produceren 128-bit identifiers, maar verschillen in entropiebron, privacykenmerken en of ze een externe installatie vereisen.

Gebruik uuid.uuid4() voor algemene unieke identifiers in webapplicaties, gedistribueerde systemen en database-primaire sleutels wanneer sorteerbaarheid niet vereist is. Gebruik uuid.uuid5() (of v3) voor deterministische ID's afgeleid van een bekende namespace en naam — bijvoorbeeld het genereren van een stabiel ID voor een canonieke URL. Schakel over naar uuid_utils.uuid7() wanneer je tijdgeordende ID's nodig hebt voor database-indexes (vermijdt pagina-splits in B-tree-indexes bij hoge invoegsnelheden). Grijp naar uuid_utils.uuid4() wanneer de ruwe generatiedoorvoer de bottleneck is.

UUID v4 vs UUID v7 — Welke moet je gebruiken?

De meest praktische vraag is of je UUID v4 of het nieuwere UUID v7 moet gebruiken voor database-primaire sleutels. Het korte antwoord: gebruik UUID v4 als standaard; schakel alleen over naar UUID v7 wanneer indexfragmentatie een gemeten probleem is.

UUID v4-waarden zijn volledig willekeurig, wat betekent dat invoegingen op willekeurige posities in een B-tree-index terechtkomen. Bij gematigde invoegsnelheden (honderden tot enkele duizenden per seconde) is dit prima — de index past in de buffergroep en willekeurige schrijfbewerkingen zijn goedkoop. Bij zeer hoge invoegsnelheden veroorzaakt willekeurige plaatsing frequente pagina-splits en cache-misses, wat de schrijfversterking vergroot en query's vertraagt.

UUID v7 bevat een millisecondeprecie Unix-tijdstempel in de meest significante bits, zodat rijen die dicht bij elkaar in de tijd worden ingevoegd ook dicht bij elkaar in de index terechtkomen. Dit geeft B-tree-indexes (PostgreSQL, MySQL, SQLite) gedrag dat dichter bij een auto-increment integer ligt: nieuwe rijen worden altijd aan het einde van de index toegevoegd, waardoor pagina-splits worden geëlimineerd. Het compromis is dat UUID v7 een tijdstempel codeert, wat de aanmaaktijd lekt — vermijd dit voor gebruikerszichtbare ID's waarbij aanmaaktijd gevoelig is.

In Python is UUID v7 nog niet in de standaardbibliotheek (vanaf Python 3.12). Genereer het met pip install uuid-utils en roep uuid_utils.uuid7() aan. Het geeft een object terug met dezelfde attribuutset als uuid.UUID, zodat migratie van v4 een één-regel wijziging is in de ID-fabriek.

Voor een éénklik-alternatief zonder Python-setup, plak je UUID-string in de UUID v4 generator en validator — die genereert, valideert en decodeert alle velden in de browser.

Veelgestelde vragen

import uuid

session_id = uuid.uuid4()
print(session_id)           # bijv. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # dezelfde canonieke string
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (zonder koppeltekens)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # 32-tekens hex, zonder koppeltekens
print(u.bytes)          # 16-byte binair
print(str(u))           # canonieke 36-tekens string met koppeltekens

import uuid, os

# uuid4 roept intern os.urandom(16) aan
raw = os.urandom(16)
# uuid4 stelt de versie- en variantbits in voordat het teruggeeft
u = uuid.UUID(bytes=raw, version=4)
print(u)  # geldige v4 UUID van onbewerkte willekeurige bytes

import uuid

def is_valid_uuid4(value: str) -> bool:
    try:
        u = uuid.UUID(value)
        return u.version == 4
    except ValueError:
        return False

print(is_valid_uuid4("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"))  # True
print(is_valid_uuid4("geen-uuid"))                               # False
print(is_valid_uuid4("3b1f8a9d-2c4e-1f6a-8b0d-5e7c9f1a3d2e"))  # False (v1, niet v4)

import uuid
import sqlite3

conn = sqlite3.connect(":memory:")
conn.execute("CREATE TABLE events (id TEXT PRIMARY KEY, name TEXT)")

event_id = uuid.uuid4()
conn.execute("INSERT INTO events VALUES (?, ?)", (str(event_id), "user_signup"))
conn.commit()

row = conn.execute("SELECT * FROM events").fetchone()
# Reconstrueer UUID-object vanuit opgeslagen string
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Genereer 5 unieke trace-ID's voor een batchverzoek
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Elke regel is een aparte UUID v4

Gerelateerde tools

• →UUID v4 Generator — Genereer UUID v4-waarden direct in de browser — geen Python-omgeving nodig. Kopieer één waarde of genereer er honderden tegelijk.
• →UUID v7 Generator — Genereer tijdgeordende UUID v7-waarden — sorteerbaar op aanmaaktijd, ideaal voor database-primaire sleutels waarbij indexfragmentatie een rol speelt.
• →UUID Decoder — Inspecteer elke UUID — versie, variant, tijdstempel (v1/v7) en knooppuntvelden — zonder zelf een parser te schrijven.
• →JWT Decoder — Decodeer en inspecteer JWT-tokens, die vaak UUID-subject-claims (sub) of jti-identificatoren bevatten naast sessie-UUID's.