fastuuid

FastUUID is a CPython extension, written in Rust and built with PyO3, that reimplements Python’s built-in uuid module on top of Rust’s uuid crate. It exposes the same UUID class shape and the same uuid1/uuid3/uuid4/uuid5/uuid7 constructors as the standard library, so existing code can switch import statements without touching call sites, while getting a native-code speedup on both generation and hex/bytes parsing.

Beyond drop-in parity, it adds bulk-generation helpers (uuid4_bulk, uuid7_bulk, and string-returning variants) that release the GIL for the full duration of generation, which lets multiple threads generate large batches of UUIDs concurrently instead of serializing on the interpreter lock. It targets services and scripts that mint UUIDs at high volume — ID generation for database rows, distributed tracing spans, or bulk data seeding — where the stdlib implementation’s Python-level overhead is measurable.

What You Get

• Drop-in UUID class - same constructor arguments (hex, bytes, bytes_le, fields, int, version) and properties (.hex, .urn, .variant, .fields, .time_low, etc.) as Python’s built-in uuid.UUID.
• All common UUID versions - uuid1, uuid_v1mc, uuid3, uuid4, uuid5, and uuid7 (time-ordered) constructors backed by Rust’s uuid crate.
• GIL-releasing bulk generation - uuid4_bulk, uuid7_bulk, and their *_as_strings_bulk variants generate large batches in native code without holding the interpreter lock, letting other Python threads run concurrently.
• Prebuilt wheels for every major platform - CI builds and publishes manylinux (glibc + musl), macOS (x86_64/arm64/universal2), and Windows wheels across Python 3.8-3.14, so installing is pip install fastuuid with no local Rust toolchain required.
• Typed stubs included - a bundled fastuuid.pyi gives full type-checker support (mypy/pyright) out of the box.

Common Use Cases

• High-throughput ID generation - services minting primary keys or idempotency tokens at high request volume, where UUID generation shows up in profiles.
• Distributed tracing and event IDs - generating trace/span/event identifiers in hot request paths where per-call overhead adds up.
• Bulk data seeding and ETL - scripts that need to pre-generate millions of UUIDs (e.g. for test fixtures or data migration) using the bulk, GIL-releasing functions.
• Strict UUID parsing - code that needs to validate/parse externally supplied UUID strings and wants stricter hexadecimal validation than the stdlib implementation.

Under The Hood

Architecture FastUUID is a single-crate CPython extension: src/lib.rs defines one #[pymodule] (fastuuid) containing a #[pyclass(subclass, freelist = 1000)] struct UUID that wraps uuid::Uuid from Rust’s uuid crate, plus free functions (uuid1, uuid3, uuid4, uuid5, uuid7, and their bulk variants) that construct and return that class. The constructor pattern-matches over the five mutually exclusive input forms (hex, bytes, bytes_le, fields, int) and an optional version override, translating each into a uuid::Builder call and mapping Rust Results to Python TypeError/ValueError exceptions with stdlib-matching messages. The class implements comparison (CompareOp), hashing, and pickling (__getstate__/__setstate__) directly against the wrapped Uuid, so the entire surface is a thin, single-layer translation between Rust value semantics and Python object semantics — there’s no internal indirection to trace, which keeps the whole extension auditable from one file.