IntToUuid: Integer ID To RFC 9562 UUID Converter

A Python library that bidirectionally converts integer IDs into RFC 9562 Version 8 UUIDs.

Overview

IntToUuid encodes a non-negative 64-bit integer identifier and an optional 32-bit namespace into a valid UUID at runtime — no need to store the UUID alongside the integer. The UUID is fully reversible: given the UUID, you can recover the original values.

The resulting UUIDs are:

• Deterministic — same inputs always produce the same UUID
• Reversible — decode any UUID back to the original integer pair
• Non-sequential — consecutive IDs produce unrelated-looking UUIDs
• Integrity-checked — UUIDs not produced by this algorithm are rejected on decode

Note: The integer values are encoded, not encrypted. A party with knowledge of this specification can recover the original values. This library mitigates casual enumeration, not determined reverse engineering.

Installation

pip install int-to-uuid

Or with uv:

uv add int-to-uuid

Usage

Encode an integer to a UUID

from int_to_uuid import IntegerId, encode

# With default namespace (0)
uuid = encode(IntegerId(42))
print(uuid)  # 99c45a05-a33b-8544-8024-f4be69401069

# With a namespace
uuid = encode(IntegerId(42, namespace=12))
print(uuid)  # dee5e9d2-c3e4-8273-b0d5-b3b5307bf749

Decode a UUID back to integers

from int_to_uuid import decode

result = decode("dee5e9d2-c3e4-8273-b0d5-b3b5307bf749")
print(result.id)         # 42
print(result.namespace)  # 12

Decode also accepts uuid.UUID objects:

import uuid
from int_to_uuid import decode

result = decode(uuid.UUID("dee5e9d2-c3e4-8273-b0d5-b3b5307bf749"))
print(result.id)         # 42
print(result.namespace)  # 12

Specification

This library implements the IntToUuid specification. See the specification for full algorithm details and test vectors.

License

This project is licensed under the MIT License. See LICENSE.md for details.