cuid2

CUID2 for Python 3. Next generation GUIDs. Collision-resistant ids optimized for horizontal scaling and performance.

A port of the CUID2 reference implementation by Parallel Drive to Python 3.

📝 Note: Originally taken from https://github.com/overflowdigital before it was unpublished. Thank you to @joshuathompsonlindley for your original contribution!

What is CUID2?

• Secure: It's not possible to guess the next ID.
• Collision resistant: It's extremely unlikely to generate the same ID twice.
• Horizontally scalable: Generate IDs on multiple machines without coordination.
• Offline-compatible: Generate IDs without a network connection.
• URL and name-friendly: No special characters.

Why?

For more information on the theory and usage of CUID2, see the following.

Improvements Over CUID

For more information on the improvements of CUID2 over CUID, see the following.

When to Use CUID2

• Zero Timestamp or Creation-Rate Leakage: Time-ordered formats (uuid.uuid7() in Python 3.14, PostgreSQL 18 uuidv7(), ULID) embed a 48-bit millisecond timestamp in their prefix, allowing anyone with a public ID to read exact creation times and infer business volume or request velocity (RFC 9562 §8). CUID2 hashes nanosecond time, CSPRNG salt, a monotonic counter, and a host fingerprint through SHA3-512, revealing nothing about when or where an ID was generated.
• HTML, CSS, and Lexical Safety ([a-z][0-9a-z]+): Every CUID2 is guaranteed to start with a lowercase ASCII letter ([a-z]) and contain only [0-9a-z]. By contrast, time-ordered UUIDv7 (019...) starts with 0 until the year 2527 (and 0–9 until year 7541), ULID always starts with a timestamp digit (0–7), UUIDv4 starts with a numeric digit (0–9) 62.5% of the time (10/16 hex values), and NanoID starts with 0–9, _, or - 18.75% of the time (12/64 alphabet chars). CUID2 IDs are always valid unescaped HTML id attributes and CSS selectors, and copy cleanly with a single double-click.
• Collision Resistance & Entropy Math:
  • 123.6-Bit Default Keyspace (length=24): 1 leading lowercase letter ($26$) followed by 23 base36 characters ($36^{23}$) yields $26 \times 36^{23} \approx \mathbf{1.61 \times 10^{37}}$ possible IDs ($\approx \mathbf{123.6\text{ bits}}$ of entropy)—slightly more than UUIDv4's 122 random bits in a 33% shorter string (24 vs. 36 chars). Reaching a 50% birthday-bound collision probability requires $\sqrt{2 \ln(2) \times 26 \times 36^{23}} \approx \mathbf{4.7 \times 10^{18}}$ IDs (generating 149 million IDs/sec continuously for 1,000 years).
  • Up to 165.0 Bits (BIG_LENGTH = 32): At length=32, the keyspace expands to $26 \times 36^{31} \approx \mathbf{4.54 \times 10^{49}}$ IDs ($\approx \mathbf{165.0\text{ bits}}$; 50% collision bound at $\approx 7.9 \times 10^{24}$ IDs).
  • Histogram De-Biasing: Because $2^{512} \approx 1.34 \times 10^{154}$ is not an exact power of 36, the most-significant base36 digit of a 512-bit SHA3-512 digest is biased toward low digits; CUID2 drops that leading hash character ([1:]) and prepends an independent uniform [a-z] letter so every character position has a uniform distribution.
• Pre-Fork & Container Snapshot Resilience: Combining os.getpid(), socket.gethostname(), environment variable keys, time.time_ns(), a randomly initialized monotonic counter (INITIAL_COUNT_MAX = 476,782,367, giving $\approx 25,700$ concurrent hosts before a 50% chance of two hosts even starting at the same counter value), and secrets.SystemRandom (os.urandom) provides defense-in-depth against PRNG or counter state collisions across forked worker processes (Gunicorn, uWSGI, Celery) and cloned VM/container snapshots.
• Polyglot ORM Compatibility (Prisma & Drizzle): Generates 24-character base36 primary keys compatible with TypeScript/Node.js services using Prisma (@default(cuid(2)) / @onCreate(cuid(2))) or Drizzle (@paralleldrive/cuid2), and replaces the deprecated CUIDv1 (cuid) format.

When to choose UUIDv7 instead: Because CUID2 hashes its inputs via SHA3-512, IDs are uniformly distributed across the key space. For write-heavy relational tables where B-tree insert locality and 16-byte binary UUID storage matter more than hiding creation timestamps, prefer Python 3.14's uuid.uuid7() or PostgreSQL 18's uuidv7().

Install

pip install cuid2

Usage

For most use cases—including Django, SQLAlchemy, and Pydantic model defaults—use the top-level create_id and is_cuid functions directly:

from cuid2 import create_id, is_cuid

my_cuid: str = create_id()
short_cuid: str = create_id(length=10)

print(is_cuid(my_cuid))  # True

Tip for Django & ORM defaults: Pass default=create_id directly on model fields (e.g., models.CharField(max_length=24, default=create_id)). Because create_id is a top-level function backed by a lazy singleton generator, Django makemigrations can serialize it directly and Cuid() initialization is deferred until the first ID is generated in each worker process.

You can also generate CUIDs directly in the terminal (optionally specifying a custom length):

$ cuid2
$ cuid2 10

If a framework, dataclass, or Django migration requires a zero-argument callable with a custom length, use functools.partial with create_id:

from functools import partial
from typing import Callable
from cuid2 import create_id

short_cuid_generator: Callable[[], str] = partial(create_id, length=10)


def main():
    short_cuid: str = short_cuid_generator()

Note: cuid_wrapper() is deprecated as of v2.1.0 and will be removed in v3.0.0. Use create_id directly for default 24-character IDs or functools.partial(create_id, length=...) for pre-configured custom lengths.

Finally, for more explicit control of the CUID generator, you can instantiate the class directly:

from cuid2 import Cuid

CUID_GENERATOR: Cuid = Cuid(length=10)


def main():
    my_cuid: str = CUID_GENERATOR.generate()
    next_cuid: str = CUID_GENERATOR.generate()

    # Validate CUID
    print(Cuid.is_cuid(my_cuid))  # True

is_cuid (and Cuid.is_cuid) also accepts optional min_length and max_length arguments to tighten the allowed length. The bounds are clamped to 2 and 98 characters, so they can narrow but never widen what is considered valid.