fastuuid

library0.14.0pypypi✓ verified 26d ago

FastUUID provides CPython bindings to a Rust UUID library, offering an API that is functionally identical to Python's built-in `uuid` module but with significantly improved performance. It supports UUID versions v1, v3, v4, v5, and v7. The current version is 0.14.0, and it maintains an active development status with regular releases.

serialization

pip install fastuuid

github ↗package ↗

INSTALL

IMPORT

SIG · FASTUUID

fastuuid

serializationpythonv0.14.0

Install

1.6s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.14.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.000s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UUID

✓ from fastuuid import UUID

uuid1

✓ from fastuuid import uuid1

uuid3

✓ from fastuuid import uuid3

uuid4

✓ from fastuuid import uuid4

uuid5

✓ from fastuuid import uuid5

uuid7

✓ from fastuuid import uuid7

Demonstrates generating a new UUID v4, parsing an existing UUID string, and using `uuid4_bulk` for efficient generation of multiple UUIDs.

from fastuuid import uuid4, UUID, uuid4_bulk # Generate a UUID v4 new_uuid = uuid4() print(f"Generated UUID v4: {new_uuid}") # Create a UUID from a string existing_uuid_str = "12345678-1234-5678-1234-567812345678" try: parsed_uuid = UUID(existing_uuid_str) print(f"Parsed UUID: {parsed_uuid}") except ValueError as e: print(f"Error parsing UUID: {e}") # Generate multiple UUID v4s efficiently (releases GIL) bulk_uuids = uuid4_bulk(100) print(f"Generated {len(bulk_uuids)} UUIDs in bulk. First one: {bulk_uuids[0]}")

Debug

Known issues

breakingInstalling `fastuuid` may require a Rust toolchain to be present on the system for compilation into CPython bindings. In environments without Rust (e.g., slim Docker images), `pip install` will fail *unless* pre-built wheels are available for your specific platform and Python version, which can prevent the need for a Rust toolchain.

fix

Ensure a Rust toolchain is installed in your build environment, or use pre-built wheels if available for your platform and Python version.

affects: All versions

gotchaFastUUID is stricter when parsing hexadecimal representations of UUIDs compared to Python's built-in `uuid` module. This means some malformed UUID strings that might have been accepted by `uuid.UUID()` previously could now raise `ValueError`.

fix

Validate UUID strings against RFC 4122 before passing them to `fastuuid.UUID()`, or implement error handling for `ValueError` during parsing.

affects: All versions

gotchaThere are multiple projects named 'fastuuid' across different languages (e.g., Go, other Rust implementations). The Python `fastuuid` library (`fastuuid/fastuuid` on GitHub) specifically aims for API compatibility with Python's standard `uuid` module and RFC 4122 compliance, supporting v1, v3, v4, v5, and v7. Other 'fastuuid' projects, especially in Go or older Rust versions, might have different characteristics, such as generating 192-bit non-RFC compliant or 'guessable' UUIDs.

fix

Verify that you are using the correct Python `fastuuid` package when comparing or migrating from other 'fastuuid' implementations to ensure expected behavior and UUID standard compliance.

affects: All versions

gotchaWhile `fastuuid.uuid4_bulk()` explicitly releases the Global Interpreter Lock (GIL) for performance when generating many UUIDs, individual calls to functions like `fastuuid.uuid4()` are not explicitly stated to release the GIL. For highly concurrent scenarios generating single UUIDs, performance benefits might be limited if the GIL is held.

fix

For high-throughput single UUID generation in multi-threaded Python applications, consider using `uuid4_bulk()` to generate a batch and then consuming from the batch, or benchmark individual generation calls in your specific use case.

affects: All versions

Errors

Common errors & fixes

error: linker `cc` not found

fastuuid relies on Rust for its CPython bindings, and compilation requires a C compiler (like `gcc` or `clang`) along with a Rust toolchain if pre-built wheels are not available for your specific platform and Python version.

fix

Install a Rust toolchain (e.g., via `rustup.rs`) and a C compiler (e.g., `sudo apt-get install build-essential` on Debian/Ubuntu, or Xcode Command Line Tools on macOS) in your build environment. Alternatively, ensure you are installing fastuuid in an environment for which pre-built wheels exist.

ValueError: badly formed hexadecimal UUID string

fastuuid enforces stricter RFC 4122 compliance when parsing UUID strings compared to Python's built-in `uuid` module. This error occurs when a UUID string does not conform to the expected 36-character format, such as missing hyphens or leading zeros in hexadecimal blocks, or containing non-hexadecimal characters.

fix

Ensure that all UUID strings strictly follow the RFC 4122 format (e.g., `xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx`). Validate input UUID strings before passing them to `fastuuid.UUID()`, or implement error handling for `ValueError`.

ModuleNotFoundError: No module named 'fastuuid'

The 'fastuuid' package is either not installed in the current Python environment, or its installation failed silently, often due to underlying compilation issues with its Rust components.

fix

Install fastuuid using `pip install fastuuid`. If the installation appears to succeed but the error persists, check the installation output for any compilation warnings or errors, particularly those related to the Rust toolchain or linker issues mentioned in other common problems.

Upgrade

Version history

0.14.0latest on PyPI · released Oct 19, 2025

Audit

Dependencies

rustrequiredCPython bindings require a Rust toolchain for compilation during installation.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/thedrow/fastuuid ↗

packagehttps://pypi.org/project/fastuuid/ ↗