cuid2

library2.0.1pypypi✓ verified 90d ago

cuid2 is a Python 3 library providing next-generation Globally Unique Identifiers (GUIDs). It's a port of the CUID2 reference implementation, optimized for horizontal scaling and performance. CUID2 IDs are secure, collision-resistant, horizontally scalable, offline-compatible, and URL-friendly, making them ideal for modern distributed systems. The library is actively maintained, with the current version being 2.0.1, and receives regular updates.

serialization database

pip install cuid2

github ↗package ↗

INSTALL

IMPORT

SIG · CUID2

cuid2

serializationpythonv2.0.1

Install

1.7s avg

Import

30ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.031s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.029s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

cuid_wrapper

✓ from cuid2 import cuid_wrapper

Recommended for simple ID generation.

Cuid

✓ from cuid2 import Cuid

✗ from cuid2 import CUID

Use 'Cuid' (capital C, lowercase uid) for explicit control over length and other settings. The 'CUID' class was deprecated in v1.3.0 and removed in v2.0.0.

This quickstart demonstrates the two primary ways to generate CUID2 identifiers: using the simple `cuid_wrapper` function for a callable generator, or instantiating the `Cuid` class for more granular control, such as specifying the ID length.

from cuid2 import cuid_wrapper, Cuid # Method 1: Using the simplified wrapper (recommended for most cases) cuid_generator = cuid_wrapper() my_cuid = cuid_generator() print(f"Generated CUID (wrapper): {my_cuid}") # Method 2: Using the Cuid class for more control (e.g., custom length) custom_cuid_generator = Cuid(length=10) short_cuid = custom_cuid_generator.generate() print(f"Generated CUID (custom length 10): {short_cuid}")

Debug

Known issues

breakingThe `CUID` class (all uppercase) was removed in version 2.0.0. It was deprecated in version 1.3.0. Attempting to import or use it will result in an `AttributeError` or `ImportError`.

fix

Migrate your code to use the `cuid_wrapper()` function for a simple generator or `Cuid(length=...)` class (note the casing: 'Cuid' with a lowercase 'uid') for customized generation. For example, `from cuid2 import Cuid`.

affects: >=2.0.0

deprecatedThe original CUID standard (v1), implemented by the separate `cuid` PyPI package, is officially deprecated due to security concerns, including information leakage (timestamps, host fingerprints) that could be exploited. CUID2 (this library) offers significantly enhanced security.

fix

For new projects, always use `cuid2`. For existing projects using the older `cuid` library, evaluate your security requirements and strongly consider migrating to `cuid2` to benefit from its improved cryptographic security and collision resistance.

affects: <all versions of `cuid` library>

gotchaCUID2 identifiers are designed to be random-looking and are not sequentially sortable by their value, nor do they encode readable timestamps or other information. This is an intentional security feature that differs from CUID v1, which had a degree of sortability.

fix

Do not rely on CUID2 IDs for sequential ordering or to extract creation timestamps. If time-based sorting is crucial for your database, consider adding a separate timestamp column. If you need strictly sequential, gap-less IDs (e.g., invoice numbers), CUID2 is not suitable; use an auto-incrementing ID or a different ID scheme designed for that purpose.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cuid2'

The `cuid2` library is not installed in your current Python environment, or your environment is not correctly configured.

fix

Run `pip install cuid2` to install the library. Ensure you are running your script in the same Python environment where you installed the package.

AttributeError: module 'cuid2' has no attribute 'CUID'

You are attempting to import or use the `CUID` class (all uppercase) which was removed in version 2.0.0 of the `cuid2` library. It was deprecated in v1.3.0.

fix

Update your import and usage to `from cuid2 import Cuid` (lowercase 'uid') for the class, or `from cuid2 import cuid_wrapper` for a simple callable ID generator.

ImportError: cannot import name 'cuid' from 'cuid2'

You are trying to import a function named `cuid` directly from the `cuid2` package, which is a common pattern for the *older, deprecated `cuid` library* (v1 standard). The `cuid2` library does not expose a top-level `cuid()` function.

fix

Instead of `from cuid2 import cuid`, use `from cuid2 import cuid_wrapper` to get a callable ID generator, or `from cuid2 import Cuid` to use the class for more control.

Upgrade

Version history

2.0.1latest on PyPI · released Apr 16, 2024

Audit

Dependencies

pythonrequiredRuntime environment requirement

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/gordon-code/cuid2 ↗

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