Changelog

Versions follow Semantic Versioning

Unreleased

Fixed

4.2.0 - 2026-11-17

Added

  • Added support for Python 3.15.

  • ULIDType, a SQLAlchemy column type for ULID values that can also be used with SQLModel. It stores values as UUID by default, or as binary or string. Install it with the new sqlalchemy extra (pip install python-ulid[sqlalchemy]).

Fixed

  • The ULID constructor now accepts bytes and bytes-like values (bytearray and memoryview), which are stored as immutable bytes. A 16-character string or an integer was previously accepted and produced an object whose str() failed or that was unhashable, so other types now raise TypeError @KuljeetSinghXDA.

  • Pydantic validation of unsupported values such as dict, float or an out-of-range int now raises pydantic.ValidationError instead of leaking TypeError or OverflowError @KuljeetSinghXDA.

  • ULID.parse() now treats any integer in the unsigned 128-bit range as a full ULID integer, instead of guessing from the number of decimal digits. Previously only integers with exactly 37 digits were accepted, so ULID.parse(int(ulid)) failed for most ULIDs @KuljeetSinghXDA.

  • ULID.from_datetime() and ULID.from_timestamp() no longer land one millisecond early when a value on an exact millisecond multiplies to just below that integer as a float @arieleven.

  • ULID.from_datetime() and ULID.from_timestamp() raise a ValueError for values before the Unix epoch instead of a bare OverflowError.

  • ULID.from_int() raises a ValueError for integers outside the unsigned 128-bit range instead of a bare OverflowError.

  • The ulid command line tool reports invalid input as a short error message with exit status 2 instead of a Python traceback.

  • import ulid no longer fails when the package metadata is missing, e.g. in applications frozen with cx_Freeze or PyInstaller. The version is now written into the package at build time.

4.1.0 - 2026-10-27

Changed

  • Dropped support for Python 3.10.

Fixed

  • The typing-extensions dependency is now also installed on Python 3.11, where it is required for typing_extensions.override.

  • Print generated and converted values when using python -m ulid, matching the ulid console command @tongwentao.

  • ULID.from_str() accepts lower case strings again, as the ULID spec defines the string representation as case insensitive. Lower case input has been rejected since 2.6.0 @reyhaan07.

4.0.1 - 2026-07-20

Changed

4.0.0 - 2026-07-20

Warning

Breaking change: the ValueProvider class and the ULID.provider class attribute have been removed. ULID generation is now handled by the new ULIDGenerator together with pluggable monotonicity policies. To customize generation, construct a ULIDGenerator (optionally with a custom clock, randomness source, or policy) and either call its generate() method or assign it to ulid.default_generator.

Added

Removed

  • Removed the ValueProvider class and the ULID.provider attribute in favour of ULIDGenerator and the monotonicity policies. Code that replaced ULID.provider or subclassed ValueProvider must migrate to a custom ULIDGenerator assigned to ulid.default_generator.

  • Removed the internal validate_type decorator. The ULID.from_* constructors still raise TypeError for arguments of the wrong type, so runtime behaviour is unchanged.

3.2.1 - 2026-07-17

Fixed

  • Corrected the build and publish pipeline and the generated source distribution. This release contains no changes to the library code.

3.2.0 - 2026-07-17

Added

  • Added transparent bidirectional UUIDv7 conversion methods (ULID.to_uuid7 and ULID.from_uuidv7) @pirate.

  • Added a --uuid7 option to the CLI’s show command to convert and output a ULID as an RFC 4122 compliant UUIDv7.

Changed

  • Dropped support for Python 3.9 and added support for Python 3.14 @Avihais12344.

  • Depend on typing-extensions only when running on Python < 3.11 @musicinmybrain.

  • Migrated package and development workflow from Hatch to uv and poethepoet.

  • Configured Flox for bootstrapping the development environment.

Fixed

  • Fixed a clock-skew bug where non-monotonic ULIDs could be generated when crossing a millisecond boundary between timestamp and randomness sampling @gaoflow.

  • Fixed warning from uv during synchronization @jaseemabid.

  • Resolved various Ruff linter warnings and Pyrefly type checker issues.

3.1.0 - 2025-08-18

Changed

  • Added Python 3.13 to the trove classifiers.

  • Optimze @property to @cached_property @WH-2099.

  • When generating ULIDs within the same millisecond, the library will ensure monotonic sort order by incrementing the randomness component by 1 bit. This process is descrbied in the spec.

Fixed

  • Sharpen regular expression for Pydantic @aplhk.

  • Fix Sphinx warnings when referencing ULID from an external project. @BoboTiG.

3.0.0 - 2024-10-11

Changed

  • Raise TypeError instead of ValueError if constructor is called with value of wrong type.

  • Update ruff linter rules and switch to hatch fmt.

Added

Fixed

2.7.0 - 2024-06-17

Changed

  • Ensure that the validation of ULID’s timestamp component aligns more closely with the ULID specification.

2.6.0 - 2024-05-26

Changed

  • Use stricter validation when a ULID value from user input. When using ULID.from_str() we will check if the characters match the base32 alphabet. In general, it is ensured that the timestamp part of the ULID is not out of range.

2.5.0 - 2024-04-26

Changed

  • Generate a more accurate JSON schema with Pydantic’s BaseModel.model_json_schema(). This includes a specification for string and byte representations.

2.4.0 - 2024-04-02

Added

  • ULID objects are now properly serialized when used as Pydantic types @Avihais12344.

2.3.0 - 2024-03-21

Added

  • ULID objects can now be converted to bytes with bytes(ulid).

  • The Pydantic v2 protocol is now supported, so that the ULID class can be directly used as type annotations in Pydantic models

Changed

  • The type annotations have been adapted, so that the classmethod constructors properly reflect the type for ULID subclasses. Thanks to @johnpaulett

2.2.0 - 2023-09-21

Added

  • Added a new flag --uuid4 to the CLI show command, that converts the provided ULID into an RFC 4122 compliant UUID.

  • The ulid build command allows the use of the special value - for all options to read its inputs from stdin. E.g.

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

2.1.0 - 2023-09-21

Added

  • The new method ULID.to_uuid4() can be used to create an RFC 4122 compliant UUID from an existing ULID.

Changed

  • The validate_types-decorator that is used for all ULID.from_*-methods to check type correctness at runtime has now better support for type hints. Thanks to @johnpaulett

2.0.0 - 2023-09-20

Added

  • New command line interface to easily generate and inspect ULIDs from the terminal

    $ ulid build
    01HASJFZZ862S826DA2NJK4WMT
    
    $ ulid show 01HASJFZZ862S826DA2NJK4WMT
    ULID:      01HASJFZZ862S826DA2NJK4WMT
    Hex:       018ab327ffe830b28119aa156532729a
    Int:       2049398682679492051963931130707735194
    Timestamp: 1695222857.704
    Datetime:  2023-09-20 15:14:17.704000+00:00
    

    The CLI can also be invoked as a module python -m ulid. For more information see ulid --help.

  • Make ULID-instances hashable. Thanks to bendykst.

  • Added support for Python 3.11.

Changed

  • Dropped support for Python 3.7 and 3.8.

1.1.0 - 2022-03-10

Added

  • Added support for Python 3.10.

  • Added __version__ variable to package.

1.0.3 - 2021-07-14

Added

  • Enable tool based type checking as described in PEP-0561 by adding the py.typed marker.

Changed

  • Use GitHub actions instead of Travis.

1.0.0 - 2020-04-30

Added

Changed

  • Dropped support for Python 2. Only Python 3.6+ is supported.

  • The named constructor ULID.new has been removed. Use one of the specifc named constructors instead. For a new ULID created from the current timestamp use the standard constructor.

    # old
    ulid = ULID.new()
    ulid = ULID.new(time.time())
    ulid = ULID.new(datetime.now())
    
    # new
    ulid = ULID()
    ulid = ULID.from_timestamp(time.time())
    ulid = ULID.from_datetime(datetime.now())
    
  • The ULID.str and ULID.int methods have been removed in favour of the more Pythonic special dunder-methods. Use str(ulid) and int(ulid) instead.

  • Added the property ULID.hex() that returns a hex representation of the ULID.

    >>> ULID().hex
    '0171caa5459a8631a6894d072c8550a8'
    
  • Equality checks and ordering now also work with str-instances.

  • The package now has no external dependencies.

  • The test-coverage has been raised to 100%.