Membuat UUID v4 di Python — Panduan uuid.uuid4()

Setiap kali saya membutuhkan identifier yang tahan tabrakan untuk baris database, trace API, atau token sesi, jawabannya adalah membuat UUID v4 di Python — satu baris, tanpa dependensi: uuid.uuid4(). Modul uuid bawaan Python menggunakan os.urandom() untuk keacakan yang aman secara kriptografis. Untuk UUID cepat tanpa menulis kode, gunakan generator UUID v4 online yang langsung bisa digunakan. Panduan ini mencakup atribut objek UUID, pembuatan massal, serialisasi JSON, penyimpanan database, validasi, uuid-utils (pengganti berbasis Rust ~10× lebih cepat), dan empat kesalahan paling umum — semuanya dengan Python 3.8+.

Apa itu UUID v4?

UUID (Universally Unique Identifier) adalah label 128-bit yang diformat sebagai 32 digit heksadesimal yang dibagi menjadi lima kelompok oleh tanda hubung: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Versi 4 adalah varian yang paling banyak digunakan: 122 dari 128 bit dihasilkan secara acak, dan 6 bit sisanya menyandikan versi (4) dan varian (RFC 4122). Tidak ada timestamp dan tidak ada identifier host — identifier ini sepenuhnya buram dan aman untuk privasi. Probabilitas dua UUID v4 yang dihasilkan secara independen mengalami tabrakan sangat kecil sehingga untuk keperluan praktis tidak pernah terjadi, bahkan pada sistem terdistribusi yang menghasilkan jutaan ID per detik.

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

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

uuid.uuid4() — Cara Standar Membuat UUID v4 di Python

Modul uuid adalah bagian dari standard library Python. Memanggil uuid.uuid4() mengembalikan objek uuid.UUID dengan sekumpulan atribut lengkap untuk berbagai representasi. Mengonversi ke string dengan str() menghasilkan format berisi tanda hubung kanonik yang diharapkan oleh API, database, dan header HTTP.

import uuid

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

# Konversi ke string untuk JSON / header HTTP
print(str(request_id))      # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
print(request_id.hex)       # "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" (tanpa tanda hubung)
print(request_id.bytes)     # b';...' (16 byte mentah)

Pola dunia nyata yang umum adalah melampirkan UUID ke setiap permintaan API keluar agar Anda dapat mengorelasikan log di seluruh layanan. Berikut adalah pembungkus sesi requests minimal yang menyuntikkan UUID baru ke setiap panggilan:

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"] memungkinkan Anda mencari permintaan persis di semua log layanan
result = call_api("https://api.example.com/v1/orders", {"product_id": "prod_7x2k", "qty": 3})
print(result["trace_id"])  # mis. "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"

Saat membuat UUID dalam jumlah besar — misalnya, mengisi sekelompok baris database terlebih dahulu — list comprehension adalah idiom yang ringkas dan mudah dibaca:

import uuid

# Buat ID terlebih dahulu untuk 1000 event telemetri
event_ids = [str(uuid.uuid4()) for _ in range(1000)]
print(f"Generated {len(event_ids)} unique IDs")
print(event_ids[0])   # mis. "a1c2e3f4-..."
print(event_ids[-1])  # nilai berbeda setiap kali

Butuh UUID cepat tanpa menjalankan kode apa pun? Gunakan generator UUID v4 online untuk menyalin nilai baru dalam satu klik, atau buat ratusan sekaligus — berguna untuk menyemai database pengujian atau mengisi file fixture.

Atribut dan Representasi Objek UUID

Objek uuid.UUID memperlihatkan berbagai representasi dari nilai 128-bit yang sama. Memilih representasi yang tepat untuk lapisan penyimpanan Anda mencegah kerusakan data yang tidak terdeteksi dan pemborosan byte.

import uuid

u = uuid.uuid4()

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

# Round-trip: rekonstruksi dari string
reconstructed = uuid.UUID("3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e")
print(reconstructed == u)  # True (jika u adalah nilai tersebut)

Untuk PostgreSQL dengan psycopg2 atau asyncpg, teruskan objek UUID langsung — driver menangani pemetaan ke tipe kolom uuid asli. Untuk SQLite, gunakan str(u) (TEXT) atau u.bytes (BLOB, 16 byte dibanding 36 untuk string). Untuk efisiensi penyimpanan pada skala besar, .bytes 55% lebih kecil dari string kanonik.

Memvalidasi dan Mengurai String UUID v4 di Python

Setiap kali UUID datang dari input pengguna, parameter path URL, atau API upstream, Anda harus memvalidasinya sebelum menggunakannya sebagai kunci database. Pendekatan idiomatis adalah mencoba konstruksi dengan uuid.UUID() dan menangkap ValueError. Anda juga dapat memastikan bahwa nilai yang masuk secara khusus adalah versi 4 dengan memeriksa .version.

import uuid

def parse_uuid4(raw: str) -> uuid.UUID:
    """
    Urai dan validasi string UUID v4.
    Memunculkan ValueError untuk format tidak valid atau versi yang salah.
    """
    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

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

    # aman digunakan uid dalam query DB sekarang
    return {"order_id": str(uid), "status": "processing"}

UUID v4 dalam Payload JSON dan Respons API

Standar JSON tidak memiliki tipe UUID — UUID dalam JSON selalu berupa string. Artinya Anda harus mengonversi objek uuid.UUID ke string sebelum meneruskannya ke json.dumps(). Pendekatan paling bersih adalah subkelas JSONEncoder kustom agar Anda tidak perlu menyebarkan panggilan str() ke seluruh basis kode Anda.

import json
import uuid
from datetime import datetime

class ApiEncoder(json.JSONEncoder):
    """Serialisasi objek UUID dan datetime dalam respons JSON."""
    def default(self, obj):
        if isinstance(obj, uuid.UUID):
            return str(obj)
        if isinstance(obj, datetime):
            return obj.isoformat()
        return super().default(obj)

# Respons API realistis dengan UUID bersarang
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-...",
#     ...
#   }
# }

Untuk panggilan serialisasi sekali pakai, hook default= lebih sederhana daripada membuat subkelas:

import json, uuid

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

# Teruskan callable; dipanggil hanya untuk tipe yang tidak bisa ditangani json
json_str = json.dumps(payload, default=str)
print(json_str)  # {"event_id": "3b1f8a9d-...", "action": "checkout"}

Saat menerima respons dari API eksternal, urai string UUID kembali ke objek agar kode Anda mendapatkan sekumpulan atribut lengkap dan keamanan tipe:

import json
import uuid
import requests

def fetch_shipment(shipment_id: str) -> dict:
    """Ambil pengiriman dan kembalikan dengan field UUID bertipe."""
    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()

    # Urai field UUID kembali ke objek 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

Untuk memperbarui field UUID dalam file JSON di disk — misalnya, merotasi correlation ID dalam file konfigurasi atau seed — baca, ubah, dan tulis kembali secara atomik:

import json, uuid

def rotate_correlation_id(path: str) -> str:
    """Ganti atau tambahkan 'correlation_id' dalam file JSON. Mengembalikan UUID baru."""
    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

Jika Anda tidak ingin menjalankan skrip setiap kali perlu memeriksa UUID dari respons API, tempelkan langsung ke UUID Decoder — menampilkan versi, varian, dan semua field tanpa kode apa pun.

Membuat UUID v4 dari Command Line dengan Python

Modul uuid Python tidak mengekspos subperintah CLI mandiri seperti python -m json.tool, tetapi satu baris perintah sudah mencakup kasus penggunaan yang sama. Ini berguna dalam skrip shell, pipeline CI, dan kapan pun Anda membutuhkan identifier sementara tanpa membuka REPL.

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

# Format tanpa tanda hubung (hex) — berguna untuk nama file dan variabel env
python3 -c "import uuid; print(uuid.uuid4().hex)"
# 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e

# Buat 5 UUID untuk skrip seed batch
python3 -c "import uuid; [print(uuid.uuid4()) for _ in range(5)]"

# Gunakan dalam variabel shell
DEPLOY_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
echo "Deploying with ID: $DEPLOY_ID"

UUID v4 Berkinerja Tinggi dengan uuid-utils

uuid.uuid4() dari standard library cukup cepat untuk sebagian besar aplikasi — dengan beberapa mikrodetik per panggilan, ia menangani ribuan ID per detik dengan nyaman. Jika Anda menghasilkan UUID di jalur panas layanan dengan throughput tinggi (penyisipan massal, telemetri per-event pada skala besar, atau pembuatan request ID di bawah beban berat), uuid-utils adalah pengganti drop-in berbasis Rust yang menurut benchmark sekitar 10x lebih cepat dari stdlib.

pip install uuid-utils

# uuid_utils adalah pengganti drop-in untuk modul uuid stdlib
import uuid_utils as uuid

# API yang sama seperti stdlib
request_id = uuid.uuid4()
print(request_id)           # 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(request_id))      # string kanonik
print(request_id.hex)       # hex tanpa tanda hubung
print(request_id.version)   # 4

# Juga mendukung v7 (terurut berdasarkan waktu, bagus untuk primary key DB)
time_ordered_id = uuid.uuid7()
print(time_ordered_id)      # diawali dengan awalan timestamp saat ini

UUID v4 dalam Dataclass dan Model Pydantic

Dataclass Python dan model Pydantic keduanya mendukung field UUID secara native. Pola kunci saat menggunakan UUID sebagai default yang dihasilkan otomatis adalah meneruskan referensi fungsi, bukan hasil panggilan — jika tidak, setiap instance berbagi UUID yang sama.

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 per instance
print(job2.job_id)  # berbeda dari 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 menyerialisasi uuid.UUID sebagai string secara otomatis

Kesalahan Umum Saat Membuat UUID v4 di Python

Saya telah melihat keempat pola ini muncul dalam code review dan insiden produksi — mudah terlewat karena tidak langsung memunculkan error.

@dataclass
class Session:
    # SALAH: dievaluasi sekali, semua instance berbagi UUID ini
    session_id: uuid.UUID = uuid.uuid4()

@dataclass
class Session:
    # BENAR: factory dipanggil per instance
    session_id: uuid.UUID = field(default_factory=uuid.uuid4)

# Mengembalikan False meskipun nilai cocok
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:   # keduanya adalah uuid.UUID
    revoke_session(record)

# Atau normalkan semuanya ke string di titik batas:
if str(record["session_id"]) == str(target):
    revoke_session(record)

# Menyimpan "3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e" — tanpa tanda hubung
payload = {"correlation_id": request_id.hex}

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

import random, secrets

# Bukan UUID — akan gagal validasi uuid.UUID()
request_id = secrets.token_hex(16)   # "a1b2c3d4e5f6..."
session_id = str(random.random())    # "0.8273..." — sama sekali tidak cocok

import uuid

request_id = str(uuid.uuid4())  # "3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e"
# UUID v4 yang valid, aman secara kriptografis

Metode Pembuatan UUID di Python — Perbandingan Cepat

Semua metode di bawah ini menghasilkan identifier 128-bit tetapi berbeda dalam sumber entropi, karakteristik privasi, dan apakah memerlukan instalasi pihak ketiga.

Gunakan uuid.uuid4() untuk identifier unik serba guna dalam aplikasi web, sistem terdistribusi, dan primary key database saat pengurutan tidak diperlukan. Gunakan uuid.uuid5() (atau v3) untuk ID deterministik yang berasal dari namespace dan nama yang diketahui — misalnya, menghasilkan ID stabil untuk URL kanonik. Beralih ke uuid_utils.uuid7() saat Anda membutuhkan ID terurut berdasarkan waktu untuk indeks database (menghindari pemisahan halaman dalam indeks B-tree pada laju penyisipan tinggi). Gunakan uuid_utils.uuid4() saat throughput pembuatan mentah menjadi bottleneck.

UUID v4 vs UUID v7 — Mana yang Sebaiknya Digunakan?

Pertanyaan praktis paling umum adalah apakah menggunakan UUID v4 atau UUID v7 yang lebih baru untuk primary key database. Jawaban singkatnya: gunakan UUID v4 secara default; beralih ke UUID v7 hanya saat fragmentasi indeks menjadi masalah yang terukur.

Nilai UUID v4 sepenuhnya acak, yang berarti penyisipan mendarat di posisi acak dalam indeks B-tree. Pada laju penyisipan sedang (ratusan hingga ribuan rendah per detik), ini tidak masalah — indeks muat di buffer pool dan penulisan acak murah. Pada laju penyisipan yang sangat tinggi, penempatan acak menyebabkan pemisahan halaman dan cache miss yang sering, meningkatkan amplifikasi penulisan dan memperlambat kueri.

UUID v7 menyematkan timestamp Unix dengan presisi milidetik di bit paling signifikan, sehingga baris yang disisipkan berdekatan dalam waktu juga mendarat berdekatan dalam indeks. Ini memberi indeks B-tree (PostgreSQL, MySQL, SQLite) perilaku yang lebih mirip integer auto-increment: baris baru selalu ditambahkan ke akhir indeks, menghilangkan pemisahan halaman. Trade-off-nya adalah UUID v7 menyandikan timestamp, yang membocorkan waktu pembuatan — hindari untuk ID yang menghadap pengguna di mana waktu pembuatan bersifat sensitif.

Di Python, UUID v7 belum ada di standard library (per Python 3.12). Buatlah dengan pip install uuid-utils dan panggil uuid_utils.uuid7(). Fungsi ini mengembalikan objek dengan sekumpulan atribut yang sama seperti uuid.UUID, sehingga migrasi dari v4 adalah perubahan satu baris di factory ID.

Untuk alternatif satu klik tanpa pengaturan Python apa pun, tempelkan string UUID Anda ke generator dan validator UUID v4 — menghasilkan, memvalidasi, dan mendekode semua field di browser.

Pertanyaan yang Sering Diajukan

import uuid

session_id = uuid.uuid4()
print(session_id)           # mis. 3b1f8a9d-2c4e-4f6a-8b0d-5e7c9f1a3d2e
print(str(session_id))      # string kanonik yang sama
print(session_id.hex)       # 3b1f8a9d2c4e4f6a8b0d5e7c9f1a3d2e (tanpa tanda hubung)

import uuid

u = uuid.uuid4()
print(type(u))          # <class 'uuid.UUID'>
print(u.version)        # 4
print(u.hex)            # hex 32 karakter, tanpa tanda hubung
print(u.bytes)          # biner 16 byte
print(str(u))           # string kanonik 36 karakter dengan tanda hubung

import uuid, os

# uuid4 secara internal memanggil os.urandom(16)
raw = os.urandom(16)
# uuid4 menetapkan bit versi dan varian sebelum dikembalikan
u = uuid.UUID(bytes=raw, version=4)
print(u)  # UUID v4 yang valid dari byte acak mentah

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, bukan 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()
# Rekonstruksi objek UUID dari string yang tersimpan
retrieved_id = uuid.UUID(row[0])
print(retrieved_id.version)  # 4

import uuid

# Buat 5 trace ID unik untuk permintaan batch
trace_ids = [str(uuid.uuid4()) for _ in range(5)]
for tid in trace_ids:
    print(tid)
# Setiap baris adalah UUID v4 yang berbeda

Alat Terkait

• →UUID v4 Generator — Buat nilai UUID v4 secara instan di browser — tanpa perlu lingkungan Python. Salin satu nilai atau buat ratusan sekaligus.
• →UUID v7 Generator — Buat nilai UUID v7 yang terurut berdasarkan waktu — dapat diurutkan berdasarkan waktu pembuatan, ideal untuk primary key database di mana fragmentasi indeks menjadi perhatian.
• →UUID Decoder — Periksa UUID apa pun — versi, varian, timestamp (v1/v7), dan field node — tanpa menulis parser dari awal.
• →JWT Decoder — Dekode dan periksa token JWT, yang sering membawa klaim subjek UUID (sub) atau identifier jti bersama UUID sesi.