Gerar UUID v4 em Python — uuid.uuid4()

Sempre que preciso de um identificador resistente a colisões para uma linha de banco de dados, rastreamento de API ou token de sessão, a resposta é gerar UUID v4 em Python — uma linha, zero dependências: uuid.uuid4(). O módulo built-in uuid do Python utiliza os.urandom() para aleatoriedade criptograficamente segura. Para obter um UUID rapidamente sem escrever código, o gerador de UUID v4 online funciona instantaneamente. Este guia aborda os atributos do objeto UUID, geração em massa, serialização JSON, armazenamento em banco de dados, validação, uuid-utils (~10× mais rápido, com backend em Rust) e os quatro erros mais comuns — tudo com Python 3.8+.

O que é UUID v4?

Um UUID (Identificador Universalmente Único) é um rótulo de 128 bits formatado como 32 dígitos hexadecimais divididos em cinco grupos por hífens: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. A versão 4 é a variante mais amplamente utilizada: 122 desses 128 bits são gerados aleatoriamente, e os 6 bits restantes codificam a versão (4) e a variante (RFC 4122). Não há timestamp nem identificador de host — o identificador é completamente opaco e seguro em termos de privacidade. A probabilidade de dois UUIDs v4 gerados independentemente colidirem é tão pequena que, para fins práticos, isso nunca acontece, mesmo em sistemas distribuídos gerando milhões de IDs por segundo.

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

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

uuid.uuid4() — A Forma Padrão de Gerar UUID v4 em Python

O módulo uuid faz parte da biblioteca padrão do Python. Chamar uuid.uuid4() retorna um objeto uuid.UUID com um conjunto completo de atributos para diferentes representações. Converter para string com str() produz o formato canônico com hífens que APIs, bancos de dados e cabeçalhos HTTP esperam.

import uuid

# Gerar um 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

# Converter para string para JSON / cabeçalhos HTTP
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (sem traços)
print(request_id.bytes)     # b';...' (16 bytes brutos)

Um padrão comum no mundo real é anexar um UUID a cada requisição de API de saída para correlacionar logs entre serviços. Veja um wrapper mínimo de sessão requests que injeta um UUID novo em cada chamada:

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"] permite localizar a requisição exata em todos os logs de serviço
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # ex: "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

Ao gerar UUIDs em massa — por exemplo, pré-populando um lote de linhas de banco de dados — uma list comprehension é a forma idiomática e legível:

import uuid

# Pré-gerar IDs para 1000 eventos de telemetria
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # ex: "a1c2e3f4-..."
print(event_ids[-1])  # valor diferente a cada execução

Precisa de um UUID rápido sem executar código? Use o gerador de UUID v4 online para copiar um valor novo com um clique, ou gere centenas de uma vez — útil para popular bancos de dados de teste ou arquivos de fixtures.

Atributos e Representações do Objeto UUID

O objeto uuid.UUID expõe múltiplas representações do mesmo valor de 128 bits. Escolher a correta para sua camada de armazenamento previne corrupção silenciosa de dados e bytes desperdiçados.

import uuid

u = uuid.uuid4()

print(str(u))         # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"  (36 chars)
print(u.hex)          # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e"      (32 chars, sem traços)
print(u.bytes)        # b';Š...'                       (16 bytes, big-endian)
print(u.bytes_le)     # b'Š...'                       (16 bytes, little-endian)
print(u.int)          # 78823... (inteiro de 128 bits)
print(u.version)      # 4
print(u.variant)      # 'specified in RFC 4122'

# Round-trip: reconstruir a partir de string
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (se u tinha esse valor)

Para PostgreSQL com psycopg2 ou asyncpg, passe o objeto UUID diretamente — o driver cuida do mapeamento para o tipo de coluna nativo uuid. Para SQLite, use str(u) (TEXT) ou u.bytes (BLOB, 16 bytes contra 36 da string). Para eficiência de armazenamento em escala, .bytes é 55% menor que a string canônica.

Validar e Analisar Strings UUID v4 em Python

Sempre que um UUID chegar de entrada do usuário, de um parâmetro de URL ou de uma API upstream, você deve validá-lo antes de usá-lo como chave de banco de dados. A abordagem idiomática é tentar a construção com uuid.UUID() e capturar ValueError. Você também pode garantir que o valor recebido seja especificamente a versão 4 verificando .version.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Analisa e valida uma string UUID v4.
    Lança ValueError para formato inválido ou versão incorreta.
    """
    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

# Uso em um handler de rota FastAPI / Flask
def get_order(order_id: str):
    try:
        uid = parse_uuid4(order_id)
    except ValueError as exc:
        return {"error": str(exc)}, 400

    # seguro para usar uid em uma consulta ao banco de dados agora
    return {"order_id": str(uid), "status": "processing"}

UUID v4 em Payloads JSON e Respostas de API

O padrão JSON não possui tipo UUID — um UUID em JSON é sempre uma string. Isso significa que você deve converter o objeto uuid.UUID para string antes de passá-lo para json.dumps(). A abordagem mais limpa é uma subclasse personalizada de JSONEncoder para não precisar espalhar chamadas str() por todo o código.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serializa objetos UUID e datetime em respostas JSON."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# Resposta de API realista com UUIDs aninhados
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-...",
#     ...
#   }
# }

Para uma serialização avulsa, o hook default= é mais simples do que criar uma subclasse:

import json, uuid

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

# Passa um callable; chamado apenas para tipos que json não suporta
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Ao receber uma resposta de uma API externa, analise as strings UUID de volta para objetos para que o código obtenha o conjunto completo de atributos e segurança de tipos:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Busca uma remessa e retorna com campos UUID tipados."""
    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()

    # Analisar os campos UUID de volta para objetos 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

Para atualizar campos UUID em um arquivo JSON no disco — por exemplo, rotacionar um ID de correlação em um arquivo de configuração ou seed — leia, modifique e grave de volta atomicamente:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Substitui ou adiciona 'correlation_id' em um arquivo JSON. Retorna o novo 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

Se não quiser executar um script toda vez que precisar inspecionar um UUID de uma resposta de API, cole-o diretamente no UUID Decoder — ele mostra a versão, variante e todos os campos sem nenhum código.

Gerar UUID v4 pela Linha de Comando com Python

O módulo uuid do Python não expõe um subcomando de CLI independente como python -m json.tool, mas um one-liner cobre o mesmo caso de uso. Esses comandos são úteis em scripts shell, pipelines de CI e sempre que você precisar de um identificador descartável sem abrir um REPL.

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

# Formato sem traços (hex) — útil para nomes de arquivo e variáveis de ambiente
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Gerar 5 UUIDs para um script de seed em lote
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Usar em uma variável shell
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

UUID v4 de Alto Desempenho com uuid-utils

O uuid.uuid4() da biblioteca padrão é rápido o suficiente para a maioria das aplicações — a alguns microssegundos por chamada, ele lida confortavelmente com milhares de IDs por segundo. Se você estiver gerando UUIDs no caminho crítico de um serviço de alto throughput (inserções em massa, telemetria por evento em escala ou geração de request ID sob carga intensa), uuid-utils é um substituto direto com backend em Rust que apresenta cerca de 10x a velocidade da stdlib nos benchmarks.

pip install uuid-utils

# uuid_utils é um substituto direto para o módulo uuid da stdlib
import uuid_utils as uuid

# Mesma API que a stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # string canônica
print(request_id.hex)       # hex sem traços
print(request_id.version)   # 4

# Também suporta v7 (ordenado por tempo, ótimo para chaves primárias de BD)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # começa com prefixo do timestamp atual

UUID v4 em Dataclasses e Modelos Pydantic

Dataclasses e modelos Pydantic do Python suportam campos UUID nativamente. O padrão essencial ao usar UUID como padrão gerado automaticamente é passar a referência da função, não o resultado de uma chamada — caso contrário, todas as instâncias compartilharão o mesmo 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)  # único por instância
print(job2.job_id)  # diferente de 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 serializa uuid.UUID como string automaticamente

Erros Comuns ao Gerar UUID v4 em Python

Já vi todos esses quatro padrões aparecerem em revisões de código e incidentes em produção — são fáceis de ignorar porque não levantam um erro imediatamente.

@dataclass
class Session:
    # ERRADO: avaliado uma vez, todas as instâncias compartilham este UUID
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # CORRETO: factory chamada por instância
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Retorna False mesmo quando os valores coincidem
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:   # ambos são uuid.UUID
    revoke_session(record)

# Ou normalize tudo para strings na fronteira:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Armazena "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — sem traços
payload = {"correlation_id": request_id.hex}

# Armazena "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e" — formato padrão
payload = {"correlation_id": str(request_id)}

import random, secrets

# Não é um UUID — falhará na validação com uuid.UUID()
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — nem perto

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# UUID v4 válido, criptograficamente seguro

Métodos de Geração de UUID em Python — Comparação Rápida

Todos os métodos abaixo produzem identificadores de 128 bits, mas diferem na fonte de entropia, características de privacidade e se requerem instalação de terceiros.

Use uuid.uuid4() para identificadores únicos de propósito geral em aplicações web, sistemas distribuídos e chaves primárias de banco de dados quando a ordenação não é necessária. Use uuid.uuid5() (ou v3) para IDs determinísticos derivados de um namespace e nome conhecidos — por exemplo, gerando um ID estável para uma URL canônica. Mude para uuid_utils.uuid7() quando precisar de IDs ordenados por tempo para índices de banco de dados (evita page splits em índices B-tree com altas taxas de inserção). Recorra a uuid_utils.uuid4() quando o throughput de geração bruta for o gargalo.

UUID v4 vs UUID v7 — Qual Usar?

A questão prática mais comum é se usar UUID v4 ou o mais recente UUID v7 para chaves primárias de banco de dados. Eis a resposta resumida: use UUID v4 por padrão; mude para UUID v7 apenas quando a fragmentação de índice for um problema medido.

Os valores UUID v4 são totalmente aleatórios, o que significa que as inserções caem em posições aleatórias em um índice B-tree. Em taxas de inserção moderadas (centenas a poucos milhares por segundo), isso é aceitável — o índice cabe no buffer pool e escritas aleatórias são baratas. Em taxas de inserção muito altas, o posicionamento aleatório causa page splits frequentes e cache misses, aumentando a amplificação de escrita e tornando as consultas mais lentas.

O UUID v7 incorpora um timestamp Unix com precisão de milissegundos nos bits mais significativos, de modo que linhas inseridas próximas no tempo também ficam próximas no índice. Isso dá aos índices B-tree (PostgreSQL, MySQL, SQLite) um comportamento mais próximo de um inteiro auto-incrementado: novas linhas sempre são anexadas ao final do índice, eliminando page splits. A desvantagem é que o UUID v7 codifica um timestamp, o que vaza o tempo de criação — evite-o para IDs voltados ao usuário onde o tempo de criação é sensível.

Em Python, o UUID v7 ainda não está na biblioteca padrão (até o Python 3.12). Gere-o com pip install uuid-utils e chame uuid_utils.uuid7(). Ele retorna um objeto com o mesmo conjunto de atributos que uuid.UUID, portanto a migração do v4 é uma mudança de uma linha na factory de IDs.

Para uma alternativa com um clique sem qualquer configuração de Python, cole sua string UUID no gerador e validador de UUID v4 — ele gera, valida e decodifica todos os campos no navegador.

Perguntas Frequentes

import uuid

session_id = uuid.uuid4()
print(session_id)           # ex: 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # mesma string canônica
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (sem traços)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # hex de 32 chars, sem traços
print(u.bytes)          # 16 bytes binários
print(str(u))           # string canônica de 36 chars com traços

import uuid, os

# uuid4 internamente chama os.urandom(16)
raw = os.urandom(16)
# uuid4 define os bits de versão e variante antes de retornar
u = uuid.UUID(bytes=raw, version=4)
print(u)  # UUID v4 válido a partir de bytes aleatórios brutos

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, não 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()
# Reconstruir objeto UUID a partir da string armazenada
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Gerar 5 trace IDs únicos para uma requisição em lote
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Cada linha é um UUID v4 distinto

Ferramentas Relacionadas

• →UUID v4 Generator — Gere valores UUID v4 instantaneamente no navegador — sem precisar de um ambiente Python. Copie um único valor ou gere centenas de uma vez.
• →UUID v7 Generator — Gere valores UUID v7 ordenados por tempo — classificáveis pela hora de criação, ideais para chaves primárias em bancos de dados onde a fragmentação de índice é um problema.
• →UUID Decoder — Inspecione qualquer UUID — versão, variante, timestamp (v1/v7) e campos do nó — sem precisar escrever um parser do zero.
• →JWT Decoder — Decodifique e inspecione tokens JWT, que frequentemente carregam identificadores UUID no campo subject (sub) ou jti junto com UUIDs de sessão.