How to Generate a UUID in Python

Python uuid Standard Library Overview

Python has built-in the uuid module since version 2.5, requiring no additional packages. The module implements UUID versions 1, 3, 4, and 5 as defined in RFC 4122, providing the UUID class and several convenient generation functions. UUID objects can not only be converted to strings but also access individual fields (time_low, time_mid, clock_seq, etc.) and multiple representations like bytes, int, and hex. This makes Python's UUID operations very flexible, suitable for scenarios requiring precise control over UUID format.

Code Examples for Generating Each UUID Version

import uuid

# UUID v4（最常用，随机生成）
id_v4 = uuid.uuid4()
print(id_v4)                    # UUID 对象
print(str(id_v4))               # 字符串表示
print(id_v4.hex)                # 无连字符
print(id_v4.bytes)              # 16 字节
print(id_v4.int)                # 整数

# UUID v1（时间戳 + MAC 地址）
id_v1 = uuid.uuid1()
print(id_v1)
print(id_v1.time)               # 时间戳字段
print(id_v1.node)               # 节点（MAC）字段

# UUID v3（MD5 哈希，确定性）
id_v3 = uuid.uuid3(uuid.NAMESPACE_URL, 'https://example.com')
print(id_v3)

# UUID v5（SHA-1 哈希，确定性）
id_v5 = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')
print(id_v5)

# 标准命名空间
print(uuid.NAMESPACE_DNS)   # 6ba7b810-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_URL)   # 6ba7b811-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_OID)   # 6ba7b812-9dad-11d1-80b4-00c04fd430c8
print(uuid.NAMESPACE_X500)  # 6ba7b814-9dad-11d1-80b4-00c04fd430c8

Formatting UUID Output

import uuid

uid = uuid.uuid4()

# 不同格式输出
print(str(uid))               # 标准格式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
print(uid.hex)                # 无连字符：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
print(str(uid).upper())       # 大写格式
print(str(uid).replace('-', ''))  # 移除连字符

# 解析 UUID 字符串
parsed = uuid.UUID('550e8400-e29b-41d4-a716-446655440000')
parsed_no_dash = uuid.UUID('550e8400e29b41d4a716446655440000')  # 无连字符也可以
parsed_braces = uuid.UUID('{550e8400-e29b-41d4-a716-446655440000}')  # 花括号

# 查看版本和变体
print(parsed.version)   # 4
print(parsed.variant)   # UUID 变体标识

# 批量生成
uuids = [str(uuid.uuid4()) for _ in range(10)]

Using UUID Primary Keys in Django

Django natively supports UUID as model primary keys using models.UUIDField. This is the recommended approach in Django for avoiding auto-increment primary keys and improving security. UUID primary keys do not expose the total count and order of database records, making them suitable for resource IDs in public-facing APIs.

# Django 模型示例
import uuid
from django.db import models

class Article(models.Model):
    id = models.UUIDField(
        primary_key=True,
        default=uuid.uuid4,  # 注意：传函数引用而非调用结果
        editable=False
    )
    title = models.CharField(max_length=200)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ['-created_at']

# 使用
article = Article(title='Hello World')
article.save()
print(article.id)       # UUID 对象
print(str(article.id))  # 字符串

Using UUID with SQLAlchemy

# SQLAlchemy 示例
import uuid
from sqlalchemy import Column, String
from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = 'users'

    # PostgreSQL 原生 UUID 类型
    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)

    # 或使用 String 兼容所有数据库
    id = Column(String(36), primary_key=True, default=lambda: str(uuid.uuid4()))

UUID Type Annotations in FastAPI

# FastAPI + Pydantic 示例
from uuid import UUID, uuid4
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    id: UUID = None
    name: str

    def __init__(self, **data):
        if 'id' not in data:
            data['id'] = uuid4()
        super().__init__(**data)

@app.get('/items/{item_id}')
async def get_item(item_id: UUID):
    # FastAPI 自动验证 item_id 是否是合法 UUID
    return {'id': str(item_id)}

@app.post('/items')
async def create_item(item: Item):
    return item

Validating UUID Strings

import uuid

def is_valid_uuid(uuid_string: str) -> bool:
    """验证字符串是否是合法的 UUID"""
    try:
        uuid.UUID(uuid_string)
        return True
    except ValueError:
        return False

def is_valid_uuid_v4(uuid_string: str) -> bool:
    """验证字符串是否是合法的 UUID v4"""
    try:
        u = uuid.UUID(uuid_string)
        return u.version == 4
    except ValueError:
        return False

# 测试
print(is_valid_uuid('550e8400-e29b-41d4-a716-446655440000'))  # True
print(is_valid_uuid('not-a-uuid'))  # False
print(is_valid_uuid_v4('550e8400-e29b-41d4-a716-446655440000'))  # False (v1)
print(is_valid_uuid_v4(str(uuid.uuid4())))  # True