uuid-utils

0.14.1 verified Tue May 12 auth: no python install: verified quickstart: verified

uuid-utils is a Python library that provides a fast, drop-in replacement for Python's standard `uuid` module, leveraging Rust for performance. It supports all standard UUID versions (1, 3, 4, 5) and also newer draft versions like UUIDv6, UUIDv7, and UUIDv8. Currently at version 0.14.1, the library maintains an active release cadence with frequent updates and performance enhancements.

pip install uuid-utils

Common errors

error ModuleNotFoundError: No module named 'uuid_utils' ↓

cause The `uuid-utils` package is not installed in the current Python environment or the environment is not active.

fix

Install the library using pip: pip install uuid-utils

error AttributeError: module 'uuid' has no attribute 'uuid7' ↓

cause You are attempting to call `uuid.uuid7()` from Python's standard `uuid` module, which does not support UUIDv6, v7, or v8. `uuid-utils` provides these newer UUID versions.

fix

Import uuid_utils and use its functions:

import uuid_utils
my_uuid_v7 = uuid_utils.uuid7()

error error: can't find Rust compiler ↓

cause `uuid-utils` is a Rust-backed Python library and requires the Rust toolchain (compiler `rustc` and package manager `cargo`) to be installed for compilation during installation.

fix

Install the Rust toolchain by following instructions on rustup.rs: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Warnings

breaking The byte-order for `uuid1` and `uuid6` was fixed in version 0.14.1. If you relied on the previous, incorrect byte-order in earlier versions, this change may break compatibility with existing data or systems. ↓

fix Review any code or stored UUIDs generated with `uuid1` or `uuid6` from versions prior to 0.14.1. Ensure that the new, correct byte order is compatible with your application's requirements.

deprecated Support for Python 3.7 was dropped in version 0.7.0. Users on Python 3.7 will not be able to upgrade to newer versions of `uuid-utils`. ↓

fix Upgrade to Python 3.8 or newer to continue receiving updates and security fixes for `uuid-utils`.

gotcha The default `UUID` class returned by `uuid_utils` is a custom class. While `uuid_utils.compat` provides functions that *mimic* the standard library's `uuid` module, it still returns `uuid_utils` custom `UUID` instances, not standard library `uuid.UUID` instances. If you specifically require standard library `uuid.UUID` instances (e.g., for ORMs like Django), direct conversion or alternative methods might be necessary. ↓

fix Be aware that even `uuid_utils.compat` functions return custom `UUID` instances. If standard library `uuid.UUID` instances are strictly required, you may need to explicitly convert `uuid_utils.UUID` instances (e.g., by creating a `uuid.UUID` object from the string representation of the `uuid_utils.UUID` instance) or reconsider using `uuid-utils` if its custom `UUID` class is fundamentally incompatible with your application's requirements.

gotcha The behavior of `getnode` was changed in version 0.14.0 to be compatible with Python's standard library `uuid.getnode()`. If your application relied on the specific behavior of `getnode` in earlier `uuid-utils` versions, this might introduce subtle changes. ↓

fix Verify that `getnode()` behavior is consistent with your expectations if you were using it prior to version 0.14.0. The new behavior aligns with `stdlib`.

gotcha While `uuid-utils` explicitly calls to 'reseed RNG in fork process' (since 0.14.0) to improve multiprocessing safety for random UUIDs, standard library's `uuid.uuid4()` has historically had issues where child processes generated identical UUIDs if the RNG was not reseeded. Although `uuid-utils` addresses this, always test UUID generation thoroughly in multiprocessing environments to ensure uniqueness. ↓

fix Ensure `uuid-utils` is at least 0.14.0 for improved multiprocessing handling. For critical applications, consider explicitly re-seeding the random number generator in child processes if you encounter collisions, or use `uuid.uuid1()` or `uuid.uuid7()` which are time-based and generally more robust in distributed systems for ordering and uniqueness.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.02s 19.1M

3.10 alpine (musl) - - 0.02s 19.1M

3.10 slim (glibc) wheel 1.6s 0.01s 19M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.01s 20.9M

3.11 alpine (musl) - - 0.02s 21.0M

3.11 slim (glibc) wheel 1.7s 0.01s 21M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) wheel - 0.00s 12.8M

3.12 alpine (musl) - - 0.01s 12.8M

3.12 slim (glibc) wheel 1.5s 0.00s 13M

3.12 slim (glibc) - - 0.00s 13M

3.13 alpine (musl) wheel - 0.00s 12.5M

3.13 alpine (musl) - - 0.00s 12.5M

3.13 slim (glibc) wheel 1.5s 0.00s 13M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) wheel - 0.02s 18.6M

3.9 alpine (musl) - - 0.02s 18.6M

3.9 slim (glibc) wheel 1.9s 0.01s 19M

3.9 slim (glibc) - - 0.02s 19M

Imports

uuid
```
import uuid_utils as uuid
```
Common pattern for a direct drop-in replacement, making most existing code compatible.
uuid4
```
from uuid_utils import uuid4
```
UUID
```
from uuid_utils.compat import UUID
```
Use the `compat` module if you require standard library `uuid.UUID` instances (e.g., for Django ORM compatibility). This incurs a slight performance penalty but is still faster than `stdlib` UUID.

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates how to generate various UUID versions using `uuid-utils`, including random (v4), time-ordered (v7), and name-based (v5) UUIDs. It also shows how to use the compatibility layer to obtain standard library `uuid.UUID` instances when required.

import uuid_utils as uuid

# Generate a random UUID (Version 4)
random_uuid = uuid.uuid4()
print(f"Random UUID (v4): {random_uuid}")

# Generate a time-ordered UUID (Version 7)
time_ordered_uuid = uuid.uuid7()
print(f"Time-ordered UUID (v7): {time_ordered_uuid}")

# Generate a name-based UUID using SHA-1 hash (Version 5)
namespace_dns = uuid.NAMESPACE_DNS
name_uuid = uuid.uuid5(namespace_dns, 'example.com')
print(f"Name-based UUID (v5) for 'example.com': {name_uuid}")

# To get a standard library UUID instance (e.g. for Django):
from uuid_utils.compat import uuid4 as compat_uuid4
compat_instance = compat_uuid4()
print(f"Compat UUID (v4): {compat_instance}")
print(f"Is compat instance a standard uuid.UUID? {isinstance(compat_instance, uuid.UUID)}")