Install & Compatibility
Where this runs
tested against v0.17.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.012s · 19.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.008s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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)}")
Debug
Known issues
breakingThe 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.fixReview 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.
affects: >=0.14.1
deprecatedSupport 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`.fixUpgrade to Python 3.8 or newer to continue receiving updates and security fixes for `uuid-utils`.
affects: <0.7.0
gotchaThe 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.fixBe 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.
affects: All versions
gotchaThe 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.fixVerify 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`.
affects: >=0.14.0
gotchaWhile `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.fixEnsure `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.
affects: <0.14.0 (partially), all versions (best practice)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'uuid_utils'
The `uuid-utils` package is not installed in the current Python environment or the environment is not active.
fixInstall the library using pip: `pip install uuid-utils`
AttributeError: module 'uuid' has no attribute 'uuid7'
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.
fixImport `uuid_utils` and use its functions: `import uuid_utils
my_uuid_v7 = uuid_utils.uuid7()`
error: can't find Rust compiler
`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.
fixInstall the Rust toolchain by following instructions on `rustup.rs`: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
Upgrade
Version history
0.17.0latest on PyPI · released Jul 9, 2026
Audit
Dependencies
No dependency data recorded yet.