UUID v4 in Python erzeugen — uuid.uuid4()

Wann immer ich einen kollisionsresistenten Bezeichner für eine Datenbankzeile, einen API-Trace oder ein Session-Token benötige, lautet die Antwort UUID v4 in Python erzeugen — eine Zeile, keine Abhängigkeiten: uuid.uuid4(). Pythons eingebautes uuid-Modul verwendet os.urandom() für kryptografisch sichere Zufälligkeit. Für eine schnelle UUID ohne Code schreiben zu müssen, liefert der Online-UUID-v4-Generator sofortige Ergebnisse. Diese Anleitung behandelt die Attribute des UUID-Objekts, Massenerzeugung, JSON-Serialisierung, Datenbankspeicherung, Validierung, uuid-utils (~10× schnelleres Rust-basiertes Drop-in) und die vier häufigsten Fehler — alles mit Python 3.8+.

Was ist UUID v4?

Eine UUID (Universally Unique Identifier) ist ein 128-Bit-Label, das als 32 hexadezimale Ziffern formatiert ist, die durch Bindestriche in fünf Gruppen aufgeteilt sind: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Version 4 ist die am weitesten verbreitete Variante: 122 der 128 Bits werden zufällig generiert, und die verbleibenden 6 Bits kodieren die Version (4) und den Variant (RFC 4122). Es gibt keinen Zeitstempel und keinen Host-Bezeichner — der Identifier ist vollständig opak und datenschutzkonform. Die Wahrscheinlichkeit einer Kollision zweier unabhängig erzeugter v4-UUIDs ist so gering, dass sie in der Praxis nie auftritt, selbst in verteilten Systemen, die Millionen von IDs pro Sekunde generieren.

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

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

uuid.uuid4() — Der Standardweg zur UUID-v4-Erzeugung in Python

Das uuid-Modul ist Teil von Pythons Standardbibliothek. Der Aufruf von uuid.uuid4() gibt ein uuid.UUID-Objekt mit einer vollständigen Menge von Attributen für unterschiedliche Darstellungen zurück. Die Konvertierung in einen String mit str() erzeugt das kanonische Format mit Bindestrichen, das von APIs, Datenbanken und HTTP-Headern erwartet wird.

import uuid

# Eine UUID v4 erzeugen
request_id = uuid.uuid4()

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

# In String für JSON / HTTP-Header konvertieren
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (ohne Bindestriche)
print(request_id.bytes)     # b';...' (16 Rohbytes)

Ein gängiges Praxis-Muster ist, jeder ausgehenden API-Anfrage eine UUID beizufügen, um Logs über Dienste hinweg korrelieren zu können. Hier ist ein minimaler requests-Session-Wrapper, der bei jedem Aufruf eine neue UUID einfügt:

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"] ermöglicht die genaue Anfrage in allen Service-Logs zu finden
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # z. B. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

Bei der Massenerzeugung von UUIDs — zum Beispiel für die Vorbefüllung eines Batches von Datenbankzeilen — ist eine List Comprehension idiomatisch und gut lesbar:

import uuid

# IDs für 1000 Telemetrie-Ereignisse vorerzeugen
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # z. B. "a1c2e3f4-..."
print(event_ids[-1])  # jedes Mal ein anderer Wert

Benötigen Sie eine schnelle UUID ohne Code auszuführen? Verwenden Sie den Online-UUID-v4-Generator um einen frischen Wert mit einem Klick zu kopieren oder Hunderte auf einmal zu generieren — nützlich zum Befüllen von Test-Datenbanken oder Fixture-Dateien.

UUID-Objekt-Attribute und Darstellungen

Das uuid.UUID-Objekt bietet mehrere Darstellungen desselben 128-Bit-Werts. Die richtige Wahl für Ihre Speicherschicht verhindert stille Datenkorrumpierung und verschwendete Bytes.

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  (36 Zeichen)
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      (32 Zeichen, ohne Bindestriche)
print(u.bytes)        # b';Š...'                       (16 Bytes, Big-Endian)
print(u.bytes_le)     # b'Š...'                       (16 Bytes, Little-Endian)
print(u.int)          # 78823... (128-Bit-Ganzzahl)
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# Round-Trip: aus String rekonstruieren
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (wenn u diesen Wert hatte)

Für PostgreSQL mit psycopg2 oder asyncpg übergeben Sie das UUID-Objekt direkt — der Treiber übernimmt die Zuordnung zum nativen uuid-Spaltentyp. Für SQLite verwenden Sie str(u) (TEXT) oder u.bytes (BLOB, 16 Bytes gegenüber 36 beim String). Für Speichereffizienz im großen Maßstab ist .bytes 55 % kleiner als der kanonische String.

UUID-v4-Strings in Python validieren und parsen

Wann immer eine UUID aus Benutzereingaben, einem URL-Pfadparameter oder einer vorgelagerten API eintrifft, sollten Sie sie vor der Verwendung als Datenbankschlüssel validieren. Die idiomatische Vorgehensweise besteht darin, die Konstruktion mit uuid.UUID() zu versuchen und ValueError abzufangen. Sie können auch prüfen, dass der eingehende Wert speziell Version 4 ist, indem Sie .version überprüfen.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Parst und validiert einen UUID-v4-String.
    Wirft ValueError bei ungültigem Format oder falscher Version.
    """
    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

# Verwendung in einem 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

    # uid kann nun sicher in einer DB-Abfrage verwendet werden
    return {"order_id": str(uid), "status": "processing"}

UUID v4 in JSON-Payloads und API-Antworten

Der JSON-Standard kennt keinen UUID-Typ — eine UUID in JSON ist immer ein String. Das bedeutet, Sie müssen das uuid.UUID-Objekt in einen String konvertieren, bevor Sie es an json.dumps() übergeben. Der sauberste Ansatz ist eine benutzerdefinierte JSONEncoder-Unterklasse, damit Sie str()-Aufrufe nicht über Ihre gesamte Codebasis verteilen müssen.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serialisiert UUID- und datetime-Objekte in JSON-Antworten."""
    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-Antwort mit verschachtelten UUIDs
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-...",
#     ...
#   }
# }

Für eine einmalige Serialisierung ist der default=-Hook einfacher als das Ableiten einer Unterklasse:

import json, uuid

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

# Callable übergeben; wird nur für Typen aufgerufen, die json nicht verarbeiten kann
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Wenn Sie eine Antwort von einer externen API empfangen, parsen Sie UUID-Strings zurück in Objekte, damit Ihr Code die vollständige Attributmenge und Typsicherheit erhält:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Lädt eine Sendung und gibt sie mit typisierten UUID-Feldern zurück."""
    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()

    # UUID-Felder zurück in uuid.UUID-Objekte parsen
    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

Um UUID-Felder in einer JSON-Datei auf der Festplatte zu aktualisieren — zum Beispiel beim Rotieren einer Korrelations-ID in einer Konfigurations- oder Seed-Datei — lesen, ändern und schreiben Sie atomar zurück:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Ersetzt oder fügt 'correlation_id' in einer JSON-Datei hinzu. Gibt die neue UUID zurück."""
    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

Wenn Sie nicht jedes Mal ein Skript ausführen möchten, um eine UUID aus einer API-Antwort zu untersuchen, fügen Sie sie direkt in den UUID Decoder ein — er zeigt Version, Variant und alle Felder ohne jeglichen Code.

UUID v4 über die Kommandozeile mit Python erzeugen

Pythons uuid-Modul bietet keinen eigenständigen CLI-Unterbefehl wie python -m json.tool, aber ein Einzeiler deckt denselben Anwendungsfall ab. Diese sind nützlich in Shell-Skripten, CI-Pipelines und immer dann, wenn Sie einen temporären Bezeichner benötigen, ohne eine REPL zu öffnen.

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

# Hex-Format ohne Bindestriche — nützlich für Dateinamen und Umgebungsvariablen
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# 5 UUIDs für ein Batch-Seed-Skript erzeugen
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# In einer Shell-Variablen verwenden
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

Hochleistungs-UUID v4 mit uuid-utils

Das uuid.uuid4() der Standardbibliothek ist für die meisten Anwendungen schnell genug — mit wenigen Mikrosekunden pro Aufruf verarbeitet es komfortabel Tausende von IDs pro Sekunde. Wenn Sie UUIDs auf dem kritischen Pfad eines Hochdurchsatz-Dienstes generieren (Masseninserts, ereignisbasierte Telemetrie im großen Maßstab oder Request-ID-Generierung unter hoher Last), ist uuid-utils ein Drop-in-Ersatz auf Rust-Basis, der in Benchmarks etwa die 10-fache Geschwindigkeit der Standardbibliothek erreicht.

pip install uuid-utils

# uuid_utils ist ein Drop-in-Ersatz für das stdlib-uuid-Modul
import uuid_utils as uuid

# Gleiche API wie stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # kanonischer String
print(request_id.hex)       # Hex ohne Bindestriche
print(request_id.version)   # 4

# Unterstützt auch v7 (zeitgeordnet, ideal für DB-Primärschlüssel)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # beginnt mit aktuellem Zeitstempel-Präfix

UUID v4 in Dataclasses und Pydantic-Modellen

Python-Dataclasses und Pydantic-Modelle unterstützen UUID-Felder beide nativ. Das entscheidende Muster bei der Verwendung von UUID als automatisch generierter Standard ist, die Funktionsreferenz zu übergeben, nicht ein Aufruf-Ergebnis — andernfalls teilen alle Instanzen dieselbe 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)  # eindeutig pro Instanz
print(job2.job_id)  # unterscheidet sich von 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 serialisiert uuid.UUID automatisch als String

Häufige Fehler bei der UUID-v4-Erzeugung in Python

Alle vier dieser Muster sind mir in Code-Reviews und Produktionsvorfällen begegnet — sie sind leicht zu übersehen, weil sie keinen unmittelbaren Fehler auslösen.

@dataclass
class Session:
    # FALSCH: einmal ausgewertet, alle Instanzen teilen diese UUID
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # RICHTIG: Factory wird pro Instanz aufgerufen
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Gibt False zurück, selbst wenn die Werte übereinstimmen
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 sind uuid.UUID
    revoke_session(record)

# Oder alles an der Grenze zu Strings normalisieren:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Speichert "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — ohne Bindestriche
payload = {"correlation_id": request_id.hex}

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

import random, secrets

# Keine UUID — schlägt bei uuid.UUID()-Validierung fehl
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — nicht mal annähernd

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# Gültige UUID v4, kryptografisch sicher

UUID-Erzeugungsmethoden in Python — Kurzvergleich

Alle unten aufgeführten Methoden erzeugen 128-Bit-Bezeichner, unterscheiden sich jedoch in der Entropiequelle, den Datenschutzeigenschaften und ob sie eine Drittanbieter-Installation erfordern.

Verwenden Sie uuid.uuid4() für allgemeine eindeutige Bezeichner in Webanwendungen, verteilten Systemen und Datenbank-Primärschlüsseln, wenn keine Sortierbarkeit erforderlich ist. Verwenden Sie uuid.uuid5() (oder v3) für deterministische IDs, die aus einem bekannten Namespace und Namen abgeleitet werden — zum Beispiel zur Erzeugung einer stabilen ID für eine kanonische URL. Wechseln Sie zu uuid_utils.uuid7(), wenn Sie zeitgeordnete IDs für Datenbankindizes benötigen (vermeidet Page Splits in B-Tree-Indizes bei hohen Einfügeraten). Greifen Sie auf uuid_utils.uuid4() zurück, wenn der rohe Erzeugungsdurchsatz der Engpass ist.

UUID v4 vs. UUID v7 — Was sollten Sie verwenden?

Die häufigste praktische Frage ist, ob man UUID v4 oder das neuere UUID v7 für Datenbank-Primärschlüssel verwenden soll. Hier ist die kurze Antwort: Verwenden Sie UUID v4 als Standard; wechseln Sie zu UUID v7 nur, wenn Index-Fragmentierung ein gemessenes Problem ist.

UUID-v4-Werte sind vollständig zufällig, was bedeutet, dass Inserts an zufälligen Positionen in einem B-Tree-Index landen. Bei moderaten Einfügeraten (Hunderte bis niedrige Tausende pro Sekunde) ist das in Ordnung — der Index passt in den Buffer Pool und zufällige Schreibvorgänge sind günstig. Bei sehr hohen Einfügeraten verursacht die zufällige Platzierung häufige Page Splits und Cache Misses, was die Schreibverstärkung erhöht und Abfragen verlangsamt.

UUID v7 bettet einen Unix-Zeitstempel mit Millisekunden-Genauigkeit in die höchstwertigen Bits ein, sodass Zeilen, die zeitlich nah beieinander eingefügt werden, auch im Index nahe beieinander landen. Dies gibt B-Tree-Indizes (PostgreSQL, MySQL, SQLite) ein Verhalten, das einem Auto-Increment-Integer näherkommt: Neue Zeilen werden immer am Ende des Index angehängt, was Page Splits eliminiert. Der Kompromiss besteht darin, dass UUID v7 einen Zeitstempel kodiert, der die Erstellungszeit preisgibt — vermeiden Sie ihn für benutzerorientierte IDs, bei denen die Erstellungszeit sensibel ist.

In Python ist UUID v7 noch nicht in der Standardbibliothek enthalten (Stand Python 3.12). Erzeugen Sie es mit pip install uuid-utils und rufen Sie uuid_utils.uuid7() auf. Es gibt ein Objekt mit demselben Attributsatz zurück wie uuid.UUID, sodass die Migration von v4 eine einzeilige Änderung in der ID-Factory ist.

Für eine Ein-Klick-Alternative ohne Python-Setup fügen Sie Ihren UUID-String in den UUID-v4-Generator und -Validator ein — er erzeugt, validiert und dekodiert alle Felder im Browser.

Häufig gestellte Fragen

import uuid

session_id = uuid.uuid4()
print(session_id)           # z. B. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # gleicher kanonischer String
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (ohne Bindestriche)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # 32-stelliger Hex-String, ohne Bindestriche
print(u.bytes)          # 16-Byte-Binärdarstellung
print(str(u))           # kanonischer 36-Zeichen-String mit Bindestrichen

import uuid, os

# uuid4 ruft intern os.urandom(16) auf
raw = os.urandom(16)
# uuid4 setzt die Versions- und Variant-Bits vor der Rückgabe
u = uuid.UUID(bytes=raw, version=4)
print(u)  # gültige v4-UUID aus rohen Zufallsbytes

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("not-a-uuid"))                              # False
print(is_valid_uuid4("3b1f8a9d-2c4e-1f6a-8b0d-5e7c9f1a3d2e"))  # False (v1, nicht 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()
# UUID-Objekt aus dem gespeicherten String rekonstruieren
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# 5 eindeutige Trace-IDs für eine Batch-Anfrage erzeugen
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Jede Zeile ist eine eindeutige UUID v4

Verwandte Tools

• →UUID v4 Generator — UUID-v4-Werte sofort im Browser erzeugen — keine Python-Umgebung erforderlich. Einzelnen Wert kopieren oder Hunderte auf einmal generieren.
• →UUID v7 Generator — Zeitgeordnete UUID-v7-Werte erzeugen — nach Erstellungszeit sortierbar, ideal für Datenbank-Primärschlüssel, bei denen Index-Fragmentierung eine Rolle spielt.
• →UUID Decoder — Beliebige UUID untersuchen — Version, Variant, Zeitstempel (v1/v7) und Node-Felder — ohne einen Parser von Grund auf schreiben zu müssen.
• →JWT Decoder — JWT-Tokens dekodieren und untersuchen, die häufig UUID-Subject-Claims (sub) oder jti-Bezeichner zusammen mit Session-UUIDs enthalten.