Registry / serialization / python-ulid

python-ulid

JSON →
library4.0.1pypypi✓ verified 28d ago

python-ulid is a Python library that provides Universally Unique Lexicographically Sortable Identifiers (ULIDs). ULIDs are designed to be compatible with UUIDs but offer better performance for database indexing due to their time-based sort order. The library is actively maintained with regular updates, currently at version 3.1.0, and often introduces new features and stricter validation.

pip install python-ulid
INSTALL
IMPORT
SIG · PYTHON-ULID
P
python-ulid
serializationpythonv4.0.1
Install
1.9s avg
Import
133ms
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 v4.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.95 runs
installs and imports cleanly · install 0.0s · import 0.084s · 18.2MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.076s · 19MB
16MB installed
● package 16MB
Code
Verified usage

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

ulid
✓ import ulid
✗ import ulid

This quickstart demonstrates how to generate ULIDs, convert them to string and bytes, parse them from strings, and shows the monotonicity feature introduced in 3.1.0 for sub-millisecond generation. It also includes conversion to UUIDs.

from ulid import ULID import time # Generate a new ULID ulid_obj = ULID() print(f"Generated ULID: {ulid_obj}") print(f"As string: {str(ulid_obj)}") print(f"As bytes: {bytes(ulid_obj)}") # requires >=2.3.0 print(f"Timestamp (float): {ulid_obj.timestamp()}") print(f"Datetime: {ulid_obj.datetime()}") # Generate multiple ULIDs quickly to demonstrate monotonicity (requires 3.1.0+) print("\nMonotonicity check (same millisecond - may not trigger in all environments):") # Simulate a very fast loop within a single millisecond ulids_in_ms = [] for _ in range(5): ulids_in_ms.append(ULID()) # Introduce a tiny delay if needed to help simulate # pass # time.sleep(0.000001) for u in ulids_in_ms: print(f" {u}") # Note: Asserting strict inequality `ulids_in_ms[i] < ulids_in_ms[i+1]` is generally true # due to monotonicity, but for simplicity, we just print here. # The library ensures ULIDs are unique and sorted within the same millisecond. # Parse a ULID from a string (ULID.parse() introduced in 3.0.0) ulid_str = "01HASJFZZ862S826DA2NJK4WMT" # Example ULID parsed_ulid = ULID.parse(ulid_str) print(f"\nParsed ULID: {parsed_ulid}") print(f"Parsed ULID equals original string: {str(parsed_ulid) == ulid_str}") # Convert to UUID (ULID.to_uuid4() introduced in 2.1.0) uuid_obj = ulid_obj.to_uuid4() print(f"Converted to UUID: {uuid_obj}")
Debug
Known issues
breakingCalling the `ULID` constructor with an invalid type argument will now raise a `TypeError` instead of a `ValueError`.
fix
Update exception handling for `ULID` constructor calls. Ensure correct types are passed to the constructor.
affects: <3.0.0
breakingParsing ULIDs from string or other inputs (`ULID.from_str`, `ULID.parse`) has become significantly stricter across versions 2.6.0, 2.7.0, and 3.0.0. Inputs that were previously accepted or silently coerced might now raise `ValueError` or `TypeError` due to invalid characters, out-of-range timestamps, or incorrect types.
fix
Ensure all input strings for ULID parsing strictly adhere to the ULID specification (Base32 alphabet, valid timestamp range). Implement robust error handling for parsing operations, particularly around `ULID.parse()` or `ULID.from_str()`.
affects: <2.6.0
gotchaAs of version 3.1.0, ULID generation within the same millisecond ensures monotonic sort order by incrementing the randomness component. While spec-compliant, this means the randomness component is not entirely 'random' when multiple ULIDs are generated in rapid succession within the same millisecond.
fix
Be aware of this behavior if your application relies on entirely independent random components even for sub-millisecond generation. For most use cases, this improves lexicographical sortability and is the desired behavior.
affects: <3.1.0
gotchaPydantic v2 protocol support for direct type annotation was introduced in version 2.3.0. If you are using `python-ulid` with Pydantic v2 and a version prior to 2.3.0, you might encounter issues with serialization or validation.
fix
Upgrade `python-ulid` to version 2.3.0 or newer for full Pydantic v2 compatibility and improved JSON schema generation.
affects: <2.3.0
Upgrade
Version history
4.0.1latest on PyPI · released Jul 20, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Resources
python-ulid — pip install python-ulid · libregistry