Generování UUID v4 v Pythonu — uuid.uuid4()

Kdykoli potřebuji identifikátor odolný vůči kolizím pro řádek v databázi, sledování API nebo token relace, odpovědí je generování UUID v4 v Pythonu — jeden řádek, nulové závislosti: uuid.uuid4(). Vestavěný modul Pythonu uuid používá os.urandom() pro kryptograficky bezpečnou náhodnost. Pro rychlé UUID bez psaní kódu funguje online generátor UUID v4 okamžitě. Tato příručka pokrývá atributy objektu UUID, hromadné generování, serializaci JSON, ukládání do databáze, validaci, uuid-utils (~10× rychlejší náhrada s backendem v Rustu) a čtyři nejčastější chyby — vše pro Python 3.8+.

Co je UUID v4?

UUID (Universally Unique Identifier) je 128bitový štítek formátovaný jako 32 hexadecimálních číslic rozdělených do pěti skupin pomlčkami: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Verze 4 je nejpoužívanější varianta: 122 z těchto 128 bitů je náhodně generováno a zbývajících 6 bitů kóduje verzi (4) a variantu (RFC 4122). Neobsahuje žádné časové razítko ani identifikátor hostitele — identifikátor je zcela neprůhledný a bezpečný z hlediska soukromí. Pravděpodobnost kolize dvou nezávisle vygenerovaných UUID v4 je tak malá, že pro praktické účely nenastane, a to ani v distribuovaných systémech generujících miliony ID za sekundu.

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

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

uuid.uuid4() — Standardní způsob generování UUID v4 v Pythonu

Modul uuid je součástí standardní knihovny Pythonu. Volání uuid.uuid4() vrátí objekt uuid.UUID s celou sadou atributů pro různé reprezentace. Převod na řetězec pomocí str() produkuje kanonický formát s pomlčkami, který očekávají API, databáze a HTTP hlavičky.

import uuid

# Vygeneruj 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

# Převod na řetězec pro JSON / HTTP hlavičky
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (bez pomlček)
print(request_id.bytes)     # b';...' (16 surových bajtů)

Běžný vzor v praxi je připojit UUID ke každému odchozímu API požadavku, abyste mohli korelovat logy napříč službami. Zde je minimální obalová třída pro requests session, která vloží nové UUID do každého volání:

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"] umožňuje dohledat přesný požadavek napříč všemi logy služeb
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # např. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

Při hromadném generování UUID — například pro předvyplnění dávky řádků v databázi — je idiomatický a čitelný přístup list comprehension:

import uuid

# Vygeneruj ID pro 1000 telemetrických událostí
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Vygenerováno {len(event_ids)} unikátních ID")
print(event_ids[0])   # např. "a1c2e3f4-..."
print(event_ids[-1])  # pokaždé jiná hodnota

Potřebujete rychlé UUID bez spuštění kódu? Použijte online generátor UUID v4 pro zkopírování nové hodnoty jedním kliknutím nebo hromadné generování stovek najednou — užitečné pro naplnění testovacích databází nebo souborů s fixture daty.

Atributy a reprezentace objektu UUID

Objekt uuid.UUID poskytuje více reprezentací téže 128bitové hodnoty. Výběr správné reprezentace pro vaši vrstvu uložení zabrání tiché datové korrupci a zbytečně spotřebovaným bajtům.

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  (36 znaků)
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      (32 znaků, bez pomlček)
print(u.bytes)        # b';Š...'                       (16 bajtů, big-endian)
print(u.bytes_le)     # b'Š...'                       (16 bajtů, little-endian)
print(u.int)          # 78823... (128bitové celé číslo)
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# Zpětná konverze: rekonstrukce z řetězce
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (pokud u mělo tuto hodnotu)

Pro PostgreSQL s psycopg2 nebo asyncpg předejte objekt UUID přímo — ovladač zajistí mapování na nativní typ sloupce uuid. Pro SQLite použijte str(u) (TEXT) nebo u.bytes (BLOB, 16 bajtů oproti 36 u řetězce). Z hlediska úspornosti uložení ve velkém měřítku je .bytes o 55 % menší než kanonický řetězec.

Validace a parsování řetězců UUID v4 v Pythonu

Kdykoli UUID přichází z uživatelského vstupu, parametru URL cesty nebo API upstream, měli byste jej validovat před použitím jako databázový klíč. Idiomatický přístup je pokus o vytvoření objektu pomocí uuid.UUID() a zachycení výjimky ValueError. Můžete také vynutit, aby příchozí hodnota byla specificky verze 4, kontrolou atributu .version.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Zpracuje a validuje řetězec UUID v4.
    Vyvolá ValueError při neplatném formátu nebo špatné verzi.
    """
    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

# Použití v obsluze route FastAPI / Flask
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # uid je bezpečné použít v DB dotazu
    return {"order_id": str(uid), "status": "processing"}

UUID v4 v JSON payloadech a odpovědích API

Standard JSON nemá typ UUID — UUID v JSON je vždy řetězec. To znamená, že musíte objekt uuid.UUID převést na řetězec před předáním do json.dumps(). Nejčistší přístup je podtřída JSONEncoder, aby nebylo nutné rozsévat volání str() po celém kódu.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serializuje objekty UUID a datetime v JSON odpovědích."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# Realistická odpověď API s vnořenými UUID
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-...",
#     ...
#   }
# }

Pro jednorázovou serializaci je parametr default= jednodušší než tvorba podtřídy:

import json, uuid

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

# Předejte volatelný objekt; volán pouze pro typy, které json neumí zpracovat
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Při přijetí odpovědi z externího API zpracujte řetězce UUID zpět na objekty, aby váš kód získal plnou sadu atributů a typovou bezpečnost:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Načte zásilku a vrátí ji s typovanými poli UUID."""
    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()

    # Zpracuj pole UUID zpět na objekty uuid.UUID
    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

Pokud chcete aktualizovat pole UUID v JSON souboru na disku — například rotovat korelační ID v konfiguračním nebo seed souboru — načtěte, upravte a atomicky zapište zpět:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Nahradí nebo přidá 'correlation_id' do JSON souboru. Vrátí nové UUID."""
    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

Pokud nechcete spouštět skript pokaždé, když potřebujete prozkoumat UUID z odpovědi API, vložte jej přímo do UUID Decoder — zobrazí verzi, variantu a všechna pole bez jakéhokoli kódu.

Generování UUID v4 z příkazové řádky s Pythonem

Pythonův modul uuid nezpřístupňuje samostatný CLI podpříkaz jako python -m json.tool, ale jednořádkový příkaz pokryje stejný případ použití. Tyto příkazy jsou užitečné ve shell skriptech, CI pipeline a kdykoli potřebujete jednorázový identifikátor bez otevírání REPL.

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

# Formát bez pomlček (hex) — vhodný pro názvy souborů a env proměnné
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Vygeneruj 5 UUID pro dávkový seed skript
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Použití v shell proměnné
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

Vysoce výkonné UUID v4 s uuid-utils

Standardní knihovní uuid.uuid4() je dostatečně rychlé pro většinu aplikací — při několika mikrosekundách na volání zvládne pohodlně tisíce ID za sekundu. Pokud generujete UUID na kritické cestě vysoce výkonné služby (hromadné vkládání, telemetrie na úrovni událostí ve velkém měřítku nebo generování request ID pod velkým zatížením), uuid-utils je náhrada kompatibilní s API, která je v benchmarcích přibližně 10× rychlejší než stdlib, s backendem v Rustu.

pip install uuid-utils

# uuid_utils je náhrada kompatibilní s API za stdlib uuid
import uuid_utils as uuid

# Stejné API jako stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # kanonický řetězec
print(request_id.hex)       # hex bez pomlček
print(request_id.version)   # 4

# Podporuje také v7 (časově řazené, skvělé pro primární klíče DB)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # začíná prefixem aktuálního časového razítka

UUID v4 v dataclasses a modelech Pydantic

Pythonové dataclasses i modely Pydantic podporují pole UUID nativně. Klíčovým vzorem při použití UUID jako automaticky generované výchozí hodnoty je předáníodkazu na funkci, nikoli výsledku volání — jinak všechny instance sdílejí stejné 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)  # unikátní pro každou instanci
print(job2.job_id)  # liší se od 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 serializuje uuid.UUID automaticky jako řetězec

Časté chyby při generování UUID v4 v Pythonu

Všechny čtyři tyto vzory jsem viděl v code review i produkčních incidentech — jsou snadno přehlédnutelné, protože okamžitě nevyvolají chybu.

@dataclass
class Session:
    # ŠPATNĚ: vyhodnoceno jednou, všechny instance sdílejí toto UUID
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # SPRÁVNĚ: factory volána pro každou instanci
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Vrátí False i při shodě hodnot
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:   # obě jsou uuid.UUID
    revoke_session(record)

# Nebo normalizujte vše na řetězce na hranici:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Uloží "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — bez pomlček
payload = {"correlation_id": request_id.hex}

# Uloží "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e" — standardní formát
payload = {"correlation_id": str(request_id)}

import random, secrets

# Není UUID — selže při validaci uuid.UUID()
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — zdaleka ne

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# Platné UUID v4, kryptograficky bezpečné

Metody generování UUID v Pythonu — rychlé srovnání

Všechny níže uvedené metody produkují 128bitové identifikátory, ale liší se zdrojem entropie, charakteristikami soukromí a tím, zda vyžadují instalaci třetí strany.

Použijte uuid.uuid4() pro obecné unikátní identifikátory ve webových aplikacích, distribuovaných systémech a primárních klíčích databází, kde není vyžadována seřaditelnost. Použijte uuid.uuid5() (nebo v3) pro deterministická ID odvozená ze známého namespace a name — například pro generování stabilního ID pro kanonickou URL. Přejděte na uuid_utils.uuid7() pokud potřebujete časově řazená ID pro databázové indexy (zabrání štěpení stránek v B-stromových indexech při vysoké frekvenci vkládání). Sáhněte po uuid_utils.uuid4() pokud je úzkým hrdlem surová propustnost generování.

UUID v4 vs UUID v7 — které použít?

Nejčastější praktická otázka je, zda používat UUID v4 nebo novější UUID v7 pro primární klíče databází. Stručná odpověď: používejte UUID v4 jako výchozí volbu; přejděte na UUID v7 pouze tehdy, když je fragmentace indexu naměřeným problémem.

Hodnoty UUID v4 jsou zcela náhodné, což znamená, že vkládání probíhá na náhodných pozicích v B-stromovém indexu. Při střední frekvenci vkládání (stovky až nízké tisíce za sekundu) je to v pořádku — index se vejde do buffer poolu a náhodné zápisy jsou levné. Při velmi vysoké frekvenci vkládání způsobuje náhodné umístění časté štěpení stránek a výpadky cache, což zvyšuje write amplification a zpomaluje dotazy.

UUID v7 vkládá unixové časové razítko s přesností na milisekundy do nejvýznamnějších bitů, takže řádky vložené v blízkém čase jsou také blízko sebe v indexu. To dává B-stromovým indexům (PostgreSQL, MySQL, SQLite) chování bližší auto-increment celému číslu: nové řádky se vždy přidávají na konec indexu, čímž se eliminuje štěpení stránek. Kompromis je, že UUID v7 kóduje časové razítko, které odhaluje čas vytvoření — vyhněte se mu pro ID viditelná uživateli, kde je čas vytvoření citlivý údaj.

V Pythonu UUID v7 zatím není ve standardní knihovně (k verzi Python 3.12). Generujte jej pomocí pip install uuid-utils a zavolejte uuid_utils.uuid7(). Vrátí objekt se stejnou sadou atributů jako uuid.UUID, takže migrace z v4 je jednořádková změna v továrně ID.

Pro jednoklikovou alternativu bez jakéhokoli Python nastavení vložte svůj UUID řetězec do generátoru a validátoru UUID v4 — generuje, validuje a dekóduje všechna pole v prohlížeči.

Často kladené otázky

import uuid

session_id = uuid.uuid4()
print(session_id)           # např. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # stejný kanonický řetězec
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (bez pomlček)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # 32znakový hex, bez pomlček
print(u.bytes)          # 16bajtová binární reprezentace
print(str(u))           # kanonický 36znakový řetězec s pomlčkami

import uuid, os

# uuid4 interně volá os.urandom(16)
raw = os.urandom(16)
# uuid4 nastaví bity verze a varianty před vrácením
u = uuid.UUID(bytes=raw, version=4)
print(u)  # platné UUID v4 z náhodných bajtů

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, nikoli 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()
# Rekonstruujte objekt UUID z uloženého řetězce
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Vygeneruj 5 unikátních trace ID pro dávkový požadavek
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Každý řádek je jiné UUID v4

Související nástroje

• →UUID v4 Generator — Generujte UUID v4 hodnoty okamžitě v prohlížeči — bez nutnosti Python prostředí. Zkopírujte jednu hodnotu nebo hromadně vygenerujte stovky najednou.
• →UUID v7 Generator — Generujte časově řazené UUID v7 hodnoty — seřaditelné podle času vytvoření, ideální pro primární klíče databází, kde záleží na fragmentaci indexů.
• →UUID Decoder — Prozkoumejte jakékoli UUID — verzi, variantu, časové razítko (v1/v7) a pole node — bez nutnosti psát vlastní parser.
• →JWT Decoder — Dekódujte a prozkoumejte JWT tokeny, které často obsahují UUID v poli subject (sub) nebo jti identifikátory spolu s UUID relací.