cuid2: Next Generation GUIDs for Python

2.0.1 · active · verified Thu Apr 16

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.

Common errors

```
ModuleNotFoundError: No module named 'cuid2'
```
cause 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'
```
cause 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'
```
cause 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.

Warnings

breaking The `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`.
deprecated The 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.
gotcha CUID2 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.

Install

pip install cuid2 Install latest version

Imports

cuid_wrapper
```
from cuid2 import cuid_wrapper
```
Recommended for simple ID generation.
Cuid
wrong:
```
from cuid2 import CUID
```
correct:
```
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.

Quickstart

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}")

view raw JSON →