Generera UUID v4 i Python — uuid.uuid4()

Varje gång jag behöver en kollisionssäker identifierare för en databasrad, API-spårning eller sessionstoken är svaret att generera UUID v4 i Python — en rad, inga beroenden: uuid.uuid4(). Pythons inbyggda uuid-modul använder os.urandom() för kryptografiskt säker slumpmässighet. För ett snabbt UUID utan att skriva kod fungerar UUID v4-generatorn online direkt. Den här guiden täcker UUID-objektets attribut, massgenerering, JSON-serialisering, databaslagring, validering, uuid-utils (~10× snabbare Rust-baserat drop-in-alternativ) och de fyra vanligaste misstagen — allt med Python 3.8+.

Vad är UUID v4?

Ett UUID (Universally Unique Identifier) är en 128-bitars etikett formaterad som 32 hexadecimala siffror uppdelade i fem grupper med bindestreck: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Version 4 är den mest använda varianten: 122 av de 128 bitarna genereras slumpmässigt, och de återstående 6 bitarna kodar versionen (4) och varianten (RFC 4122). Det finns ingen tidsstämpel och ingen värdidentifierare — identifieraren är helt ogenomskinlig och integritetssäker. Sannolikheten att två oberoende genererade v4-UUIDs kolliderar är så liten att det för praktiska ändamål aldrig inträffar, även i distribuerade system som genererar miljontals ID:n per sekund.

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

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

uuid.uuid4() — Standardsättet att generera UUID v4 i Python

Modulen uuid är en del av Pythons standardbibliotek. Att anropa uuid.uuid4() returnerar ett uuid.UUID-objekt med en fullständig uppsättning attribut för olika representationer. Konvertering till en sträng med str() ger det kanoniska bindestrecksformat som API:er, databaser och HTTP-headers förväntar sig.

import uuid

# Generera ett 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

# Konvertera till sträng för JSON / HTTP-headers
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (inga bindestreck)
print(request_id.bytes)     # b';...' (16 råa bytes)

Ett vanligt verkligt mönster är att bifoga ett UUID till varje utgående API-begäran så att du kan korrelera loggar mellan tjänster. Här är en minimal requests-sessionswrapper som injicerar ett nytt UUID i varje anrop:

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"] låter dig söka exakt begäran i alla tjänstloggar
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # t.ex. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

När du genererar UUIDs i bulk — till exempel för att fylla en batch av databasrader i förväg — är ett list comprehension idiomatiskt och läsbart:

import uuid

# Förgenerera ID:n för 1000 telemetrihändelser
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # t.ex. "a1c2e3f4-..."
print(event_ids[-1])  # olika värde varje gång

Behöver du ett snabbt UUID utan att köra någon kod? Använd UUID v4-generatorn online för att kopiera ett nytt värde med ett klick, eller massgenera hundratals på en gång — användbart för att initiera testdatabaser eller fylla fixture-filer.

UUID-objektets attribut och representationer

Objektet uuid.UUID exponerar flera representationer av samma 128-bitarsvärde. Att välja rätt representation för ditt lagringslager förhindrar tyst datakorruption och slösade bytes.

import uuid

u = uuid.uuid4()

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

# Tur och retur: rekonstruera från sträng
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (om u var det värdet)

För PostgreSQL med psycopg2 eller asyncpg skickar du UUID-objektet direkt — drivrutinen hanterar mappningen till den inbyggda uuid-kolumntypen. För SQLite använder du str(u) (TEXT) eller u.bytes (BLOB, 16 bytes jämfört med 36 för strängen). För lagringseffektivitet i stor skala är .bytes 55% mindre än den kanoniska strängen.

Validera och parsa UUID v4-strängar i Python

När ett UUID anländer från användarindata, en URL-sökvägsparameter eller ett externt API bör du validera det innan du använder det som en databasnyckel. Det idiomatiska tillvägagångssättet är att försöka konstruera med uuid.UUID() och fånga ValueError. Du kan också tvinga fram att det inkommande värdet specifikt är version 4 genom att kontrollera .version.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Parsa och validera en UUID v4-sträng.
    Kastar ValueError för ogiltigt format eller fel 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

# Användning i en FastAPI / Flask-routehanterare
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # säkert att använda uid i en DB-fråga nu
    return {"order_id": str(uid), "status": "processing"}

UUID v4 i JSON-nyttolaster och API-svar

JSON-standarden har ingen UUID-typ — ett UUID i JSON är alltid en sträng. Det innebär att du måste konvertera uuid.UUID-objektet till en sträng innan du skickar det till json.dumps(). Det renaste tillvägagångssättet är en anpassad JSONEncoder-underklass så att du aldrig behöver sprida str()-anrop genom hela kodbasen.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serialisera UUID- och datetime-objekt i JSON-svar."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# Realistiskt API-svar med nästlade 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 ett engångsserialiseringsanrop är default=-kroken enklare än att skapa en underklass:

import json, uuid

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

# Skicka ett anropbart objekt; anropas bara för typer json inte kan hantera
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

När du tar emot ett svar från ett externt API bör du parsa UUID-strängarna tillbaka till objekt så att din kod får den fullständiga attributuppsättningen och typsäkerheten:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Hämta en försändelse och returnera med typade UUID-fält."""
    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()

    # Parsa UUID-fälten tillbaka till uuid.UUID-objekt
    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

För att uppdatera UUID-fält i en JSON-fil på disk — till exempel rotera ett korrelations-ID i en konfigurations- eller seed-fil — läser du, muterar och skriver tillbaka atomärt:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Ersätt eller lägg till 'correlation_id' i en JSON-fil. Returnerar det nya UUID:t."""
    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

Om du inte vill köra ett skript varje gång du behöver inspektera ett UUID från ett API-svar klistrar du in det direkt i UUID Decoder — den visar version, variant och alla fält utan någon kod.

Generera UUID v4 från kommandoraden med Python

Pythons uuid-modul exponerar inte ett fristående CLI-underkommando som python -m json.tool, men en one-liner täcker samma användningsfall. Dessa är användbara i skalskript, CI-pipelines och när du behöver en tillfällig identifierare utan att öppna en REPL.

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

# Hex-format utan bindestreck — användbart för filnamn och miljövariabler
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Generera 5 UUIDs för ett batch-seed-skript
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Använd i en skalvariabel
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

Högpresterande UUID v4 med uuid-utils

Standardbibliotekets uuid.uuid4() är tillräckligt snabb för de flesta applikationer — med några mikrosekunder per anrop hanterar den tusentals ID:n per sekund utan problem. Om du genererar UUIDs på den kritiska vägen för en tjänst med hög genomströmning (massinsättningar, händelsetelemetri i stor skala, eller begärans-ID-generering under hög last) är uuid-utils ett drop-in-alternativ drivet av Rust som benchmarkas till ungefär 10 gånger hastigheten av stdlib.

pip install uuid-utils

# uuid_utils är ett drop-in-alternativ för stdlib uuid-modulen
import uuid_utils as uuid

# Samma API som stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # kanonisk sträng
print(request_id.hex)       # hex utan bindestreck
print(request_id.version)   # 4

# Stöder även v7 (tidssorterat, utmärkt för DB-primärnycklar)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # börjar med aktuellt tidsstämpelprefix

UUID v4 i dataklasser och Pydantic-modeller

Pythons dataklasser och Pydantic-modeller har båda inbyggt stöd för UUID-fält. Det viktigaste mönstret när du använder UUID som ett automatiskt genererat standardvärde är att skickafunktionsreferensen, inte ett anropsresultat — annars delar alla instanser samma 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)  # unikt per instans
print(job2.job_id)  # skiljer sig från 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 serialiserar uuid.UUID som sträng automatiskt

Vanliga misstag när du genererar UUID v4 i Python

Jag har sett alla fyra dessa mönster dyka upp i kodgranskningar och produktionsincidenter — de är lätta att missa eftersom de inte ger ett fel omedelbart.

@dataclass
class Session:
    # FEL: utvärderas en gång, alla instanser delar detta UUID
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # RÄTT: factory anropas per instans
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Returnerar False även när värdena matchar
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:   # båda är uuid.UUID
    revoke_session(record)

# Eller normalisera allt till strängar vid gränssnittet:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Lagrar "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — inga bindestreck
payload = {"correlation_id": request_id.hex}

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

import random, secrets

# Inte ett UUID — misslyckas med uuid.UUID()-validering
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — inte ens nära

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# Giltigt UUID v4, kryptografiskt säkert

UUID-genereringsmetoder i Python — snabb jämförelse

Alla metoder nedan producerar 128-bitars identifierare men skiljer sig åt i entropikälla, integritetsegenskaper och huruvida de kräver en tredjepartsinstallation.

Använd uuid.uuid4() för allmänna unika identifierare i webbapplikationer, distribuerade system och databasprimärnycklar när sorterbarhet inte krävs. Använd uuid.uuid5() (eller v3) för deterministiska ID:n härledda från ett känt namnrymd och namn — till exempel för att generera ett stabilt ID för en kanonisk URL. Byt till uuid_utils.uuid7() när du behöver tidssorterade ID:n för databasindex (undviker siddelningar i B-trädindex vid höga infogningshastigheter). Använd uuid_utils.uuid4() när rågenereringsgenomströmning är flaskhalsen.

UUID v4 mot UUID v7 — vilket bör du använda?

Den vanligaste praktiska frågan är om man ska använda UUID v4 eller det nyare UUID v7 för databasprimärnycklar. Här är det korta svaret: använd UUID v4 som standard; byt till UUID v7 bara när indexfragmentering är ett uppmätt problem.

UUID v4-värden är helt slumpmässiga, vilket innebär att infogningar hamnar på slumpmässiga positioner i ett B-trädindex. Vid måttliga infogningshastigheter (hundratals till låga tusentals per sekund) är detta bra — indexet ryms i buffertpoolen och slumpmässiga skrivningar är billiga. Vid mycket höga infogningshastigheter orsakar slumpmässig placering frekventa siddelningar och cachemissar, vilket ökar skriv-amplifikationen och saktar ner frågor.

UUID v7 bäddar in en Unix-tidsstämpel med millisekundsprecision i de mest signifikanta bitarna, så rader som infogas nära varandra i tid hamnar också nära varandra i indexet. Detta ger B-trädindex (PostgreSQL, MySQL, SQLite) ett beteende som liknar ett auto-inkrement heltal: nya rader läggs alltid till i slutet av indexet och eliminerar siddelningar. Avvägningen är att UUID v7 kodar en tidsstämpel, vilket läcker skapelsetid — undvik det för användarsynliga ID:n där skapelsetiden är känslig.

I Python finns UUID v7 inte ännu i standardbiblioteket (från och med Python 3.12). Generera det med pip install uuid-utils och anropa uuid_utils.uuid7(). Det returnerar ett objekt med samma attributuppsättning som uuid.UUID, så migrering från v4 är en enradsändring i ID-fabriken.

För ett enkelklicksalternativ utan någon Python-konfiguration klistrar du in din UUID-sträng i UUID v4-generatorn och validatorn — den genererar, validerar och avkodar alla fält i webbläsaren.

Vanliga frågor

import uuid

session_id = uuid.uuid4()
print(session_id)           # t.ex. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # samma kanoniska sträng
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (inga bindestreck)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # 32-teckens hex, inga bindestreck
print(u.bytes)          # 16-byte binär
print(str(u))           # kanonisk 36-teckens sträng med bindestreck

import uuid, os

# uuid4 anropar os.urandom(16) internt
raw = os.urandom(16)
# uuid4 sätter versions- och variantbitar innan det returnerar
u = uuid.UUID(bytes=raw, version=4)
print(u)  # giltigt v4 UUID från råa slumpmässiga 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("not-a-uuid"))                              # False
print(is_valid_uuid4("3b1f8a9d-2c4e-1f6a-8b0d-5e7c9f1a3d2e"))  # False (v1, inte 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()
# Rekonstruera UUID-objekt från lagrad sträng
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Generera 5 unika spårnings-ID:n för en batchbegäran
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Varje rad är ett distinkt UUID v4

Relaterade verktyg

• →UUID v4 Generator — Generera UUID v4-värden direkt i webbläsaren — ingen Python-miljö krävs. Kopiera ett enskilt värde eller massgenerera hundratals på en gång.
• →UUID v7 Generator — Generera tidssorterade UUID v7-värden — sorterbara efter skapelsetid, idealiska för databasprimärnycklar där indexfragmentering är ett problem.
• →UUID Decoder — Inspektera vilket UUID som helst — version, variant, tidsstämpel (v1/v7) och nodfält — utan att skriva en parser från grunden.
• →JWT Decoder — Avkoda och inspektera JWT-tokens, som ofta bär UUID-subject-anspråk (sub) eller jti-identifierare tillsammans med sessions-UUIDs.