Skip to main content

Universally Unique Lexicographically Sortable Identifier

Project description

Build Status codecov Code Climate Issue Count

PyPI Version PyPI Versions

Documentation Status

Stories in Ready

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
$ cd ulid && python 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

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)

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 =
>>> u
>>> u.timestamp()
>>> u.randomness()

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

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

>>> import ulid
>>> u =
>>> u
>>> u.timestamp()
>>> u.timestamp().int
>>> u.timestamp().bytes
>>> u.timestamp().datetime
datetime.datetime(2017, 6, 16, 5, 2, 2, 893000)
>>> u.randomness().bytes
>>> u.bytes[6:] == u.randomness().bytes
>>> u.str

A MemoryView also provides rich comparison functionality.

>>> import datetime, time, ulid
>>> u1 =
>>> time.sleep(5)
>>> u2 =
>>> 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), datetime.datetime(2017, 6, 16, 5, 7, 26, 775000), datetime.datetime(2039, 1, 1, 8, 0)]

Future Items

  • Collection of benchmarks to track performance.
  • Backport to Python 2.7?
  • See Github Issues for more!


A fast implementation in pure python of the spec with binary format support.


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

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


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

Randomness * 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

Project details

Release history Release notifications

This version
History Node


History Node


History Node


History Node


History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
ulid_py-0.0.6-py2.py3-none-any.whl (19.6 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Oct 28, 2017
ulid-py-0.0.6.tar.gz (10.8 kB) Copy SHA256 hash SHA256 Source None Oct 28, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page