Open-source project
oklog/ulid avatar
oklog/ulid

oklog/ulid: sortable IDs in Go, and the three entropy decisions

Universally Unique Lexicographically Sortable Identifier (ULID) in Go

5,054 stars195 forksGoApache-2.0

At a glance

What is it?
A Go port of ulid/javascript that encodes a millisecond timestamp and 80 bits of entropy into 26 characters, with a binary layout for storage. The library is small and settled, so the real work is choosing an entropy source and deciding whether you need monotonic ordering inside a single millisecond.
Who is it for?
Use oklog/ulid when your keys are created in order and later range-scanned, and pick the entropy source deliberately: crypto/rand if IDs must be unguessable, a monotonic reader if order inside one millisecond matters more. Stay on UUIDs when you never sort by ID.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 17 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • oklog/ulid5,054 ★ · +9
Star history
Repository2026-09-232026-11-15
oklog/ulid5k5.1k

9 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

UUID v4 fragmentation is the reason this package exists

Randomness on its own is the problem this library was written against. The background section names four ways a GUID or UUID disappoints: 128 bits is not the most character efficient way to encode that much entropy, UUID v1 and v2 need access to a unique stable MAC address, v3 and v5 need a unique seed while still producing randomly distributed IDs, and v4 provides no other information than randomness. Random distribution is the expensive part. Keys that do not arrive in order turn index inserts into scattered page writes instead of appends.

A ULID puts a timestamp in front of that entropy, so identifiers sort lexicographically by the moment they were created. This repository is a Go port of ulid/javascript and implements the binary format as well as the string form, which lets you keep 16 octets in a column and render 26 characters only when a human reads them. Reach for it when IDs are minted in order and later paged, sorted or range queried. The project is blunt about the other case: if you do not care about time based ordering there is no reason to use ULIDs, and you should consider UUIDs instead.

48 bits of time, 80 bits of entropy, 26 characters

The bit budget is fixed and easy to reason about. The components are encoded as 16 octets, each written Most Significant Byte first in network byte order. The specification diagram splits those bytes into 32_bit_uint_time_high, then a row holding 16_bit_uint_time_low beside 16_bit_uint_random, then a closing 32_bit_uint_random. The timestamp half is 48 bits of UNIX time in milliseconds and does not run out of space until the year 10889 AD. Collision headroom inside one millisecond is quoted as 1.21e+24 unique ULIDs, which is 1,208,925,819,614,629,174,706,176 to be exact.

Text form uses Crockford's base32 at five bits per character, so those 128 bits become 26 characters against UUID's 36. The alphabet is 0123456789ABCDEFGHJKMNPQRSTVWXYZ, with I, L, O and U excluded to avoid confusion and abuse. That single choice buys three properties the project claims: case insensitivity, no special characters, and URL safety.

ulid.Make draws from a reader you never supply

Install the module, then print an identifier:

shell
go get github.com/oklog/ulid/v2
go
fmt.Println(ulid.Make())
// 01G65Z755AFWAKHE12NY0CQ9FH

ulid.Make takes no arguments. It calls time.Now for the timestamp and reads entropy from a process-global source that is pseudo-random and monotonic, which is why it needs no setup and why you cannot hand it your own reader. When you want control over either half, compose the value with ulid.New:

go
entropy := rand.New(rand.NewSource(time.Now().UnixNano()))
ms := ulid.Timestamp(time.Now())
fmt.Println(ulid.New(ms, entropy))
// 01G65Z755AFWAKHE12NY0CQ9FH

ulid.Timestamp takes a time.Time and returns the uint64 millisecond value, and the same number comes from time.Time.UnixMilli if you already hold one. The io.Reader passed to ulid.New is where the security decision happens, and the next section is about that decision.

Inside one millisecond, order comes from the random half

ULIDs are automatically monotonic, and the qualifier is millisecond precision. Two IDs created in the same millisecond are ordered by their random component, so within that millisecond they are unordered by default. Any test that assumes insertion order inside a batch is testing something the format does not promise.

Two helpers change that. ulid.MonotonicEntropy and ulid.LockedMonotonicEntropy produce IDs that increase within a given millisecond, and the documentation attaches caveats to both that you are expected to read before wiring them in. Take them when a sort key has to be a total order, leave them out when throughput inside a millisecond is what you are actually measuring.

Per goroutine entropy removes the lock and the guarantees

Entropy choice is where this package hands you a decision with a warning printed right above it. The example builds a math/rand.Rand, and the text notes that math/rand.Rand is not safe for concurrent use by multiple goroutines. A source seeded from time.Now().UnixNano() is also reproducible in the sense that anyone who knows roughly when your process started can guess the stream.

For security-sensitive use the answer is not a matter of taste: use cryptographically secure entropy from crypto/rand. For concurrent generation the documentation offers two directions. Give each goroutine its own source, which removes lock contention but cannot make strong guarantees about the random data and does not provide monotonicity within a millisecond. Or pool sources of entropy with sync.Pool, which the project calls a common performance optimisation. x/exp/rand and its LockedSource sit in between as a safer math/rand. Whichever route you take, the cost of the lock is the thing worth measuring against your own write rate rather than assuming.

cmd/ulid exists so fixtures can be deterministic

The repository ships a command line tool under cmd/ulid, installed separately from the library:

shell
go install github.com/oklog/ulid/v2/cmd/ulid@latest
shell
Usage: ulid [-hlqz] [-f <format>] [parameters ...]
 -f, --format=<format>  when parsing, show times in this format: default, rfc3339, unix, ms
 -h, --help             print this help text
 -l, --local            when parsing, show local time instead of UTC
 -q, --quick            when generating, use non-crypto-grade entropy
 -z, --zero             when generating, fix entropy to all-zeroes

Both generation flags exist for controlled situations. -q swaps in non-crypto-grade entropy, so anything minted with it must not be treated as unguessable. -z fixes entropy to all zeroes, which leaves the timestamp as the only variable in the output, exactly what a deterministic fixture wants and exactly what makes every ID printed in that second share a suffix. Parsing is where the other two flags work:

shell
$ ulid
01D78XYFJ1PRM1WPBCBT3VHMNV
$ ulid -z
01D78XZ44G0000000000000000
$ ulid 01D78XZ44G0000000000000000
Sun Mar 31 03:51:23.536 UTC 2019
$ ulid --format=rfc3339 --local 01D78XZ44G0000000000000000
2019-03-31T05:51:23.536+02:00

Default output is UTC; -l switches the parse side to local time, and -f picks default, rfc3339, unix or ms.

go.mod still says go 1.15 and every import carries /v2

Module metadata tells you what an upgrade will cost. The module path is github.com/oklog/ulid/v2, so the /v2 suffix is mandatory in every import. go.mod declares go 1.15 and requires exactly one dependency, github.com/pborman/getopt, which is what produces the getopt style flag listing in the command line tool. The library itself is a single ulid.go with ulid_test.go beside it, and the top level also carries CHANGELOG.md, CONTRIBUTING.md, AUTHORS.md and an Apache-2.0 LICENSE. A code base that small is easy to read in full before you depend on it.

Release cadence is uneven. v2.1.2 shipped on 2026-07-23, v2.1.1 on 2025-05-22, and v2.1.0 on 2022-07-11, and the last push to the default branch was on 2026-10-29. Two bits of drift are worth knowing before you file issues. The badge links still point at a master branch although the default branch is main, and the monotonicity link in the specification targets the pre-v2 godoc path while the rest of the page uses /v2. Copying that one link lands you on documentation for an older API.

Editorial conclusion

Use oklog/ulid when your keys are created in order and later range-scanned, and pick the entropy source deliberately: crypto/rand if IDs must be unguessable, a monotonic reader if order inside one millisecond matters more. Stay on UUIDs when you never sort by ID. Before importing, check that your Go version clears the go 1.15 directive in go.mod and that every import carries the /v2 suffix required by the module path.

Frequently asked questions

What is ULID used for?

ULID is a 128 bit identifier built from a millisecond timestamp plus 80 bits of entropy, encoded as 26 characters so that IDs sort lexicographically by creation time. In this Go package ulid.Make covers the simple case and ulid.New takes a timestamp and an io.Reader when you want to supply both halves yourself.

Is ULID better than UUID?

Only when you need ordering. UUID v4 carries no information beyond randomness, which can fragment data structures, while a ULID sorts by its embedded timestamp at 26 characters instead of 36. The project's own position is that if you do not care about time based ordering there is no reason to use ULIDs, and UUIDs are easier and smaller.

Can you provide an example of an ULID?

ulid.Make() prints a value such as 01G65Z755AFWAKHE12NY0CQ9FH, and a string of that shape splits into a 10 character timestamp followed by 16 characters of entropy. The command line tool prints 01D78XYFJ1PRM1WPBCBT3VHMNV for a plain run, and with -z it prints 01D78XZ44G0000000000000000.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. oklog/ulid on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/oklog-ulid.svg)](https://hysenlabs.com/projects/oklog-ulid)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/oklog-ulid.svg)](https://hysenlabs.com/projects/oklog-ulid)

Was this useful?