Universally-Unique, Lexicographically-Sortable Identifier python implementation

Programming language: Python
License: Apache License 2.0
Tags: Random Generator     Ulid     Unique-id     Uuid    
Latest version: v0.2.0

ulid-py alternatives and similar packages

Based on the "Random Generator" category.
Alternatively, view ulid alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of ulid-py or a related project?

Add another 'Random Generator' Package



Build Status Build Status codecov Code Climate Issue Count

PyPI Version PyPI Versions

Documentation Status

Universally Unique Lexicographically Sortable Identifier in Python 3.


This project is actively maintained.


To install ulid from pip:

    $ pip install ulid-py

To install ulid from source:

    $ git clone [email protected]:ahawker/ulid.git
    $ cd ulid && python setup.py install


Create a brand new ULID.

The timestamp value (48-bits) is from time.time() with millisecond precision.

The randomness value (80-bits) is from os.urandom().

>>> import ulid
>>> ulid.new()

Create a new ULID from an existing 128-bit value, such as a UUID.

Supports ULID values as int, bytes, str, and UUID types.

>>> import ulid, uuid
>>> value = uuid.uuid4()
>>> value
>>> ulid.from_uuid(value)

Create a new ULID from an existing timestamp value, such as a datetime object.

Supports timestamp values as int, float, str, bytes, bytearray, memoryview, datetime, Timestamp, and ULID types.

>>> import datetime, ulid
>>> ulid.from_timestamp(datetime.datetime(1999, 1, 1))

Create a new ULID from an existing randomness value.

Supports randomness values as int, float, str, bytes, bytearray, memoryview, Randomness, and ULID types.

>>> import os, ulid
>>> randomness = os.urandom(10)
>>> ulid.from_randomness(randomness)

For cases when you don't necessarily control the data type (input from external system), you can use the parse method which will attempt to make the correct determination for you. Please note that this will be slightly slower than creating the instance from the respective from_* method as it needs to make a number of type/conditional checks.

Supports values as int, float, str, bytes, bytearray, memoryview, uuid.UUID, and ULID types.

>>> import ulid
>>> value = db.model.get_id()  ## Unsure about datatype -- Could be int, UUID, or string?
>>> ulid.parse(value)

Once you have a ULID object, there are a number of ways to interact with it.

The timestamp method will give you a snapshot view of the first 48-bits of the ULID while the randomness method will give you a snapshot of the last 80-bits.

>>> import ulid
>>> u = ulid.new()
>>> u
>>> u.timestamp()
>>> u.randomness()

The ULID, Timestamp, and Randomness classes all derive from the same base class, a MemoryView.

A MemoryView provides the bin, bytes, hex, int, oct, and str, methods for changing any values representation.

>>> import ulid
>>> u = ulid.new()
>>> u
>>> u.timestamp()
>>> u.timestamp().int
>>> u.timestamp().bytes
>>> u.timestamp().datetime
datetime.datetime(2017, 6, 16, 5, 2, 2, 893000, tzinfo=datetime.timezone.utc)
>>> u.randomness().bytes
>>> u.bytes[6:] == u.randomness().bytes
>>> u.str
>>> u.int
>>> u.bin
>>> u.hex
>>> u.oct

A MemoryView also provides rich comparison functionality.

>>> import datetime, time, ulid
>>> u1 = ulid.new()
>>> time.sleep(5)
>>> u2 = ulid.new()
>>> u1 < u2
>>> u3 = ulid.from_timestamp(datetime.datetime(2039, 1, 1))
>>> u1 < u2 < u3
>>> [u.timestamp().datetime for u in sorted([u2, u3, u1])]
[datetime.datetime(2017, 6, 16, 5, 7, 14, 847000, tzinfo=datetime.timezone.utc), datetime.datetime(2017, 6, 16, 5, 7, 26, 775000, tzinfo=datetime.timezone.utc), datetime.datetime(2039, 1, 1, 8, 0, tzinfo=datetime.timezone.utc)]

Monotonic Support

This library supports two implementations for stronger guarantees of monotonically increasing randomness.

To use these implementations, simply import and alias it as ulid. They supports an identical interface as ulid, so no additional changes should be necessary.

Thread lock

The "thread lock" implementation is a simple implementation that follows that of the ulid/spec. When two or more identifiers are created with the same millisecond, the subsequent identifiers use the previous identifiers randomness value + 1. See PR 473 for more details.

>>> import time
>>> from ulid import monotonic as ulid

>>> ts = time.time()
>>> ulid.from_timestamp(ts)
>>> ulid.from_timestamp(ts)
>>> ulid.from_timestamp(ts)


The "microsecond" implementation is not defined in the ulid/spec. It uses a microsecond clock and uses those additional 10-bits into the first two bytes of the randomness value. This means that two identifiers generated within the same millisecond will be monotonically ordered. If two identifiers are generated within the same microsecond, they are ordered entirely by the randomness bytes. See PR 476 for more details.

>>> from ulid import microsecond as ulid
>>> ulid.new()
>>> ulid.new()
>>> ulid.new()
>>> ulid.new()


If you would like to contribute, simply fork the repository, push your changes and send a pull request. Pull requests will be brought into the master branch via a rebase and fast-forward merge with the goal of having a linear branch history with no merge commits.


[Apache 2.0](LICENSE)

Why not UUID?

UUID can be suboptimal for many uses-cases because:

  • It isn't the most character efficient way of encoding 128 bits of randomness
  • UUID v1/v2 is impractical in many environments, as it requires access to a unique, stable MAC address
  • UUID v3/v5 requires a unique seed and produces randomly distributed IDs, which can cause fragmentation in many data structures
  • UUID v4 provides no other information than randomness which can cause fragmentation in many data structures

ULID provides:

  • 128-bit compatibility with UUID
  • 1.21e+24 unique ULIDs per millisecond
  • Lexicographically sortable!
  • Canonically encoded as a 26 character string, as opposed to the 36 character UUID
  • Uses Crockford's base32 for better efficiency and readability (5 bits per character)
  • Case insensitive
  • No special characters (URL safe)


Below is the current specification of ULID as implemented in this repository.

The binary format is implemented.

 01AN4Z07BY      79KA1307SR9X4MV3

|----------|    |----------------|
 Timestamp          Randomness
  10chars            16chars
   48bits             80bits



  • 48 bit integer
  • UNIX-time in milliseconds
  • Won't run out of space till the year 10895 AD.


  • 80 bits
  • Cryptographically secure source of randomness, if possible


The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed


Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.


Binary Layout and Byte Order

The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).

0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
|                      32_bit_uint_time_high                    |
|     16_bit_uint_time_low      |       16_bit_uint_random      |
|                       32_bit_uint_random                      |
|                       32_bit_uint_random                      |

String Representation


t is Timestamp
r is Randomness


*Note that all licence references and agreements mentioned in the ulid-py README section above are relevant to that project's source code only.