Developer Interface

ULID

class ulid.ULID(value: bytes | None = None)

classmethod from_bytes(bytes_: bytes) → Self

Create a new ULID-object from sequence of 16 bytes.

classmethod from_datetime(value: datetime) → Self

Create a new ULID-object from a datetime. The timestamp part of the ULID will be set to the corresponding timestamp of the datetime.

Examples

>>> from datetime import datetime
>>> ULID.from_datetime(datetime.now())
ULID(01E75QRYCAMM1MKQ9NYMYT6SAV)

classmethod from_hex(value: str) → Self

Create a new ULID-object from 32 character string of hex values.

classmethod from_int(value: int) → Self

Create a new ULID-object from an int.

classmethod from_str(string: str) → Self

Create a new ULID-object from a 26 char long string representation.

classmethod from_timestamp(value: float) → Self

Create a new ULID-object from a timestamp. The timestamp can be either a float representing the time in seconds (as it would be returned by time.time()) or an int in milliseconds.

Examples

>>> import time
>>> ULID.from_timestamp(time.time())
ULID(01E75QWN5HKQ0JAVX9FG1K4YP4)

classmethod from_uuid(value: uuid.UUID) → Self

Create a new ULID-object from a uuid.UUID. The timestamp part will be random in that case.

Examples

>>> from uuid import uuid4
>>> ULID.from_uuid(uuid4())
ULID(27Q506DP7E9YNRXA0XVD8Z5YSG)

classmethod from_uuidv7(value: uuid.UUID) → Self

Create a new ULID from a UUIDv7 (uuid.UUID version 7).

Extracts the timestamp from the UUIDv7’s first 48 bits (milliseconds since epoch) and the remaining 80 bits as randomness. The timestamp is always transparently preserved, providing perfect round-trip conversion with to_uuidv7().

Examples

>>> uuid7 = uuid.UUID("01936c5e-f4c0-7000-8000-000000000000")
>>> ulid = ULID.from_uuidv7(uuid7)
>>> ulid.datetime
datetime.datetime(2025, 11, 10, ...)

classmethod parse(value: Any) → Self

Create a new ULID-object from a given value.

Note

This method should only be used when the caller is trying to parse a ULID from a value when they’re unsure what format/primitive type it will be given in.

to_uuid() → UUID

Convert the ULID to a uuid.UUID.

to_uuid4() → UUID

Convert the ULID to a uuid.UUID compliant to version 4 of RFC 4122.

This conversion is destructive in the sense that the uuid.UUID cannot be converted back to the same ULID. This is because the bits for the variant and version information have to be set accordingly changing the original byte sequence.

Examples

>>> ulid = ULID()
>>> uuid = ulid.to_uuid4()
>>> uuid.version
4

to_uuid7(*, compliant: bool = False) → UUID

Convert the ULID to a UUIDv7 (uuid.UUID version 7).

UUIDv7 encodes a Unix timestamp in milliseconds in the first 48 bits (just like ULID). The timestamp is always transparently preserved regardless of compliant mode.

Parameters:

compliant – If True, sets RFC 4122 version (0x7) and variant (0b10) bits, losing 6 bits of randomness. If False (default), preserves all 80 bits of randomness by clobbering version/variant bits, enabling perfect round-trip conversion. Most tools (PostgreSQL, standard libraries) accept non-compliant UUIDv7s.

Examples

>>> ulid = ULID()
>>> uuid7 = ulid.to_uuidv7()  # Perfect round-trip
>>> assert ULID.from_uuidv7(uuid7) == ulid
>>> uuid7_compliant = ulid.to_uuidv7(compliant=True)  # RFC 4122 compliant
>>> uuid7_compliant.version
7

property datetime: datetime

Return the timestamp part as timezone-aware datetime in UTC.

Examples

>>> ulid.datetime
datetime.datetime(2020, 4, 30, 14, 33, 27, 560000, tzinfo=datetime.timezone.utc)

property hex: str

Encode the ULID-object as a 32 char sequence of hex values.

property milliseconds: int

The timestamp part as epoch time in milliseconds.

Examples

>>> ulid.milliseconds
1588257207560

provider = <ulid.ValueProvider object>

The ULID object consists of a timestamp part of 48 bits and of 80 random bits.

 01AN4Z07BY      79KA1307SR9X4MV3
|----------|    |----------------|
 Timestamp          Randomness
   48bits             80bits

You usually create a new ULID-object by calling the default constructor with no arguments. In that case it will fill the timestamp part with the current datetime. To encode the object you usually convert it to a string:

>>> ulid = ULID()
>>> str(ulid)
'01E75PVKXA3GFABX1M1J9NZZNF'

Parameters:

value (bytes, None) – A sequence of 16 bytes representing an encoded ULID.

Raises:

ValueError – If the provided value is not a valid encoded ULID.

property timestamp: float

The timestamp part as epoch time in seconds.

Examples

>>> ulid.timestamp
1588257207.56