guizmaii-opensource / zio-uuid   1.0.0

Apache License 2.0 GitHub

UUID V1, V6, V7 & TypeID generation with ZIO

Scala versions: 3.x 2.13


Production Ready CI Badge Sonatype Releases Sonatype Snapshots javadoc zio-uuid

zio-uuid is a "ZIOfied" fork of uuid4cats-effect by Antoine Comte


This library adds support for the following types:

time-based sortable random
gregorian calendar
gregorian calendar
unix epoch

Implementation based on this UUID RFC Draft

In addition to UUID, there is also support for TypeIDs. TypeIDs are a modern, type-safe extension of UUIDv7

ZIO implementation note:
Note, that we don't provide a UUIDv4 implementation in this lib. ZIO is already providing one with ZIO.randomWith(_.nextUUID)


In order to use this library, we need to add the following line in our build.sbt file:

libraryDependencies += "com.guizmaii" %% "zio-uuid" % "1.0.0"


import zio.uuid.*

val ids =
    for {
      uuid1 <- UUIDGenerator.uuidV7
      uuid2 <- UUIDGenerator.uuidV7
      typeid <- TypeIDGenerator.generate("myprefix")
    } yield (uuid1, uuid2, typeid.value)

⚠️ Warnings ⚠️

Uniqueness of generated time-based UUIDs is guaranteed when using the same generator.

The generators are stateful! They are using a Ref internally to keep track of their internal state.

The UUIDGenerator and TypeIDGenerator companion object are providing accessor functions to ease their usage but, because the generators are stateful, the way the generator instance is provided to these functions calls can lead to generated UUIDs/TypeIDs being invalid regarding the RFC.

Do not do this:

val id0 = UUIDGenerator.uuidV7.provideLayer(
val id1 = UUIDGenerator.uuidV7.provideLayer(

This will lead to non-monotonically increasing UUIDs/TypeIDs, which is invalid regarding the RFCs.

Do this instead:

  for {
    id0 <- UUIDGenerator.uuidV7
    id1 <- UUIDGenerator.uuidV7
    // ...
  } yield ()

The best way to inject a UUIDGenerator or a TypeIDGenerator instance is to inject its live layer in the boot sequence of your program so that the same instance is reused everywhere in your program and you don't risk any issue.


Learn more on the zio-uuid homepage!


For the general guidelines, see ZIO contributor's guide.

Code of Conduct

See the Code of Conduct


Come chat with us on Badge-Discord.


This library is a fork of the uuid4cats-effect library made by Antoine Comte (



Copyright 2023-2023 Jules Ivanic and the zio-uuid contributors.