PyUUID7

Fast UUID v4, v5, and v7 generation for Python, implemented in Rust with PyO3.

pyuuid7 is useful when you need standard UUID strings from Python code while keeping generation fast and dependency-light. It supports random UUIDs, deterministic name-based UUIDs, time-sortable UUIDs, validation, version detection, and canonical parsing.

Installation

pip install pyuuid7

Quick Start

import pyuuid7

user_id = pyuuid7.uuid7()
request_id = pyuuid7.uuid4()
tenant_id = pyuuid7.uuid5(
    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "example.com",
)

print(user_id)
print(request_id)
print(tenant_id)

All generated values are returned as canonical UUID strings:

019389a1-2b3c-7d4e-8f5a-6b7c8d9e0f1a

Features

Common Use Cases

Generate Time-Sortable IDs

UUID v7 includes a Unix timestamp and random data. The resulting strings sort naturally by creation time, which makes them a good fit for database primary keys, logs, events, and queues.

import pyuuid7

order = {
    "id": pyuuid7.uuid7(),
    "status": "pending",
}

print(order["id"])

Use UUID v7 in Application Models

from dataclasses import dataclass, field
from typing import Optional

import pyuuid7


@dataclass
class Event:
    id: str = field(default_factory=pyuuid7.uuid7)
    name: str = ""
    payload: Optional[dict] = None


event = Event(name="user.created", payload={"user_id": "123"})

Create Deterministic IDs with UUID v5

UUID v5 returns the same UUID every time you pass the same namespace and name. This is useful when you want stable IDs for external resources, slugs, tenant names, or imported records.

import uuid

import pyuuid7

customer_id = pyuuid7.uuid5(str(uuid.NAMESPACE_DNS), "customer.example.com")

if customer_id is None:
    raise ValueError("Invalid namespace UUID")

Validate and Normalize User Input

Use parse() when you want to accept UUID input in supported formats and store it in canonical lowercase form.

import pyuuid7


def normalize_uuid(value: str) -> str:
    parsed = pyuuid7.parse(value)
    if parsed is None:
        raise ValueError("Invalid UUID")
    return parsed


resource_id = normalize_uuid("urn:uuid:A1B2C3D4-E5F6-4A7B-8C9D-0E1F2A3B4C5D")
print(resource_id)
# a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

Route Behavior by UUID Version

import pyuuid7


def describe_uuid(value: str) -> str:
    version = pyuuid7.get_version(value)
    if version is None:
        return "invalid UUID"
    if version == 7:
        return "time-sortable UUID"
    if version == 4:
        return "random UUID"
    if version == 5:
        return "name-based UUID"
    return f"UUID version {version}"

UUID Versions

Error Handling

Functions that can fail because of invalid input return None:

import pyuuid7

assert pyuuid7.uuid5("invalid", "example.com") is None
assert pyuuid7.get_version("invalid") is None
assert pyuuid7.parse("invalid") is None

is_valid() returns False for invalid input:

import pyuuid7

assert pyuuid7.is_valid("invalid") is False

API Reference

uuid4() -> str

Generate a random UUID v4 string.

uuid5(namespace: str, name: str) -> str | None

Generate a deterministic UUID v5 string from a namespace UUID and a name. Returns None when namespace is not a valid UUID.

uuid7() -> str

Generate a time-sortable UUID v7 string.

is_valid(uuid_str: str) -> bool

Return True when uuid_str can be parsed as a UUID.

get_version(uuid_str: str) -> int | None

Return the UUID version number, or None when the input is invalid.

parse(uuid_str: str) -> str | None

Parse a UUID string and return the canonical lowercase representation, or None when the input is invalid.

Development

This project uses mise for tool versions and uv for Python dependency management.

# Install pinned tools
mise install

# Setup the development environment
mise run setup

# Build and install the extension in editable mode
mise run dev

# Run Python tests
mise run test

# Run Rust tests
mise exec -- cargo test

# Build distribution artifacts
mise run build

License

MIT