Skip to main content

Universally unique lexicographically sortable identifier

Project description

A ULID is a universally unique lexicographically sortable identifier. It is

  • 128-bit compatible 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)

In general the structure of a ULID is as follows:

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

For more information have a look at the original specification.


Use pip to install the library

$ pip install python-ulid

to include Pydantic support install the optional dependency like so

$ pip install python-ulid[pydantic]

Basic Usage

Create a new ULID object from the current timestamp

>>> from ulid import ULID
>>> ULID()

or use one of the named constructors

>>> import time, datetime
>>> ULID.from_timestamp(time.time())
>>> ULID.from_datetime(

There are several options for encoding the ULID object (e.g. string, hex, int, bytes, UUID):

>>> str(ulid)
>>> ulid.hex
>>> int(ulid)
>>> bytes(ulid)
>>> ulid.to_uuid()

It is also possible to directly access the timestamp component of a ULID, either in UNIX epoch or as datetime.datetime

>>> ulid.timestamp
>>> ulid.datetime
datetime.datetime(2017, 9, 20, 22, 18, 59, 153000, tzinfo=datetime.timezone.utc)

Pydantic integration

The ULID class can be directly used for the popular data validation library Pydantic like so

from pydantic import BaseModel
from ulid import ULID

class Model(BaseModel):
  ulid: ULID

model = Model(ulid="DX89370400440532013000")  # OK
model = Model(ulid="not-a-ulid")  # Raises ValidationError

Command line interface

The package comes with a CLI interface that can be invoked either by the script name ulid or as python module python -m ulid. The CLI allows you to generate, inspect and convert ULIDs, e.g.

$ ulid build

$ ulid build --from-datetime=2023-09-23T10:20:30

Hex:       018ab2f9aea8ccffacef7900e6555299
Int:       2049395013039097460549394558635823769
Timestamp: 1695219822.248
Datetime:  2023-09-20 14:23:42.248000+00:00

There are several flags to select specific output formats for the show command, e.g.

$ ulid show --datetime 01HASFKBN8SKZTSVVS03K5AMMS
2023-09-20 14:23:42.248000+00:00

The special character - allows to read values from stdin so that they can be piped. E.g.

$ echo 01HASFKBN8SKZTSVVS03K5AMMS | ulid show --uuid -

$ date --iso-8601 | python -m ulid build --from-datetime -

For a full overview of flags for the build and show commands use the --help option (e.g. ulid show --help).

Other implementations

Project details

Download files

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

Source Distribution

python_ulid-2.6.0.tar.gz (24.8 kB view hashes)

Uploaded Source

Built Distribution

python_ulid-2.6.0-py3-none-any.whl (10.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page