xid keeps the Mongo Object ID bytes and swaps the encoding for 20 sortable characters
xid is a globally unique id generator thought for the web
At a glance
- What is it?
- xid is a Go library for globally unique IDs that reuses the Mongo Object ID algorithm with a base32hex string form. It needs no machine or data center configuration, embeds time to the second, and is explicitly not cryptographically secure.
- Who is it for?
- xid fits server code that wants a short, sortable, configuration free identifier, and the read accessors give the machine, process, time and counter back for logging. It does not fit anything that needs unguessable IDs, and a deployment that already runs a central ID service may prefer one it can control.
- Can I use it commercially?
- Yes. MIT 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 64 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 14, 2026, and from our analysis. They are not legal advice.
Star history
- rs/xid4,281 ★ · +0
| Repository | 2026-09-23 | 2026-11-14 |
|---|---|---|
| rs/xid | 4.3k | 4.3k |
0 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The bytes are Mongo Object ID, only the serialization differs
The layout is borrowed wholesale from the Mongo Object ID: 4 bytes holding the seconds since the Unix epoch, a 3 byte machine identifier, a 2 byte process id, and a 3 byte counter that starts from a random value. The binary form stays compatible with Mongo 12 byte Object IDs, so an xid can live wherever the original type already lives. What changes is how those 12 bytes become text. Instead of the 24 character hexadecimal string an Object ID prints as, xid serializes to base32hex without padding, which brings the printable form down to 20 characters and keeps it URL safe. The size stays at 12 bytes, or 96 bits, which places it between a Snowflake at 8 bytes and a UUID at 16. The install step is a single go get:
go get github.com/rs/xidand the shortest program prints one:
guid := xid.New()
println(guid.String())
// Output: 9m4e2mr0ui3e8a215n4gbase32hex was chosen for the two encodings it rules out
The alphabet is argued rather than asserted. Base64 is rejected because case sensitivity and two non alphanumeric characters cause trouble when an identifier travels as a string between various systems. Base36 is rejected for three stated reasons: it is not a standard, the resulting size is not predictable because it is not bit aligned, and the value would not stay sortable. The hex variant of base32 answers the third point, since the ordering of the hex alphabet preserves the sort order of the bytes underneath. Validation is simple enough to write as a pattern. An xid is expected to be 20 characters long, all lowercase letters from a to v and digits from 0 to 9, written as [0-9a-v]{20}. That character range is the practical signature of the format, and it is what tells a valid xid apart from a truncated one or from a UUID fragment.
The 3 byte counter is the throughput ceiling per host
Three of the 12 bytes are a counter, and the feature list turns that into a number: uniqueness is guaranteed for 16,777,216 unique IDs per second per host and per process. The rest of the layout exists to make that counter safe. The timestamp comes first and the counter follows, so IDs come out K-ordered and a lexicographic sort of the string form matches generation order. Time is embedded with one second precision, enough to read back and not enough to separate two IDs issued in the same second by design. The counter begins at a random value rather than at zero, which keeps two processes on one machine from starting their sequences in step. K-ordered output is listed as a feature in its own right rather than as a side effect, and it is what lets a sorted index over the string form stay in generation order. The whole scheme is lock free, and that is the point the feature list contrasts with UUIDv1 and UUIDv2, both of which need a lock. Both the seconds field and the counter sit at fixed positions in the value, so two IDs issued in the same second by one process differ only in the last three bytes.
The machine identifier is five platform files and one fallback
Telling processes apart needs a machine identifier, and the repository keeps that lookup in a file per operating system: hostid_linux.go, hostid_darwin.go, hostid_windows.go, hostid_openbsd.go and hostid_freebsd.go, plus hostid_fallback.go for whatever none of them covers. The stated design goal was no configuration at all, so the value is derived from the host instead of being handed in by a deployment. Configuration remains available when the derived value is not what you want: the environment variable XID_MACHINE_ID overrides it, described as fine tuning control over generation. Three bytes carry that value, so the machine and the process are part of the identifier rather than metadata beside it, and both come back out of an existing ID:
guid.Machine()
guid.Pid()
guid.Time()
guid.Counter()Those four accessors are the reason the layout keeps them in the clear.
The benchmark measures against a UUID that needs a global lock
Performance is documented rather than asserted. The benchmark runs against a Go UUID implementation and reports xid at 91.1 ns/op with 32 B/op and one allocation on one machine, 55.9 ns/op on two, and 32.3 ns/op on four, so the generator improves as CPUs are added. The same run shows UUIDv1 at 204, 160 and 195 ns/op with 48 B/op and one allocation, and the explanation is that UUIDv1 requires a global lock, which is why its numbers do not follow the same curve. UUIDv4 is the outlier at 1503 ns/op with 64 B/op and two allocations, over a million iterations against ten to fifty million for the others:
BenchmarkXID 20000000 91.1 ns/op 32 B/op 1 allocs/op
BenchmarkXID-2 20000000 55.9 ns/op 32 B/op 1 allocs/op
BenchmarkXID-4 50000000 32.3 ns/op 32 B/op 1 allocs/op
BenchmarkUUIDv1 10000000 204 ns/op 48 B/op 1 allocs/op
BenchmarkUUIDv1-2 10000000 160 ns/op 48 B/op 1 allocs/op
BenchmarkUUIDv1-4 10000000 195 ns/op 48 B/op 1 allocs/op
BenchmarkUUIDv4 1000000 1503 ns/op 64 B/op 2 allocs/op
BenchmarkUUIDv4-2 1000000The table stops mid row on the last line, and no Go version or machine is named for the figures. go.mod asks for Go 1.16.
The notes rule out unpredictable IDs in two sentences
Unpredictability is addressed head on. An xid depends on the system time and a monotonic counter, and the notes say plainly that it is not cryptographically secure, with the instruction that if unpredictability of IDs is important you should not use xids. The same passage adds that most other UUID-like implementations are not cryptographically secure either, and points at libraries built on cryptographically secure sources such as /dev/urandom on unix and crypto/rand in Go. So the ordering guarantee and the machine and process identity are bought with being guessable by anyone who knows roughly when a process started and roughly how many IDs it has issued since. The README says xid is best used with zerolog's RequestIDHandler.
Thirteen ports, and a tag list that stops in 2018
The repository points at ports in Python, Scala, Rust, a Python wrapper around the Rust port, Ruby, Java, Dart, PostgreSQL, Swift, C++, two TypeScript and JavaScript ports and Gleam, each credited to a named author. That is the widest part of the project. The release history is not: the visible tags are v1.1 on 2017-06-07, v1.1.0 on 2018-05-23 and v1.2.1 on 2018-08-30, the last of them carrying a note that it removed a dependency on x/sys. The last commit on the default branch landed on 2026-09-12, long after that tag, so the working tree has moved past what a versioned install would give you. Continuous integration files from two eras sit side by side at the root, .travis.yml and .appveyor.yml, next to a .golangci.yml for linting and the workflow directory that the badge points at. The Go source itself is a short list of files: id.go for the type and its methods, error.go for the errors, id_test.go for the tests, the five hostid_ files, and a b/ directory. Two of the ports share an author, the Swift library and the C++ one, while the two TypeScript and JavaScript ports come from different maintainers, the Dart port is published on pub.dev, and the PostgreSQL port is written as a database extension.
Editorial conclusion
xid fits server code that wants a short, sortable, configuration free identifier, and the read accessors give the machine, process, time and counter back for logging. It does not fit anything that needs unguessable IDs, and a deployment that already runs a central ID service may prefer one it can control. Before adopting it, decide whether the 24 bit counter per host per second is enough, check whether XID_MACHINE_ID has to be pinned to keep identifiers unique across hosts, and remember that the newest tag is v1.2.1 from 2018 while the branch has moved on since.
Frequently asked questions
How does xid compare with UUID and Snowflake?
The comparison table puts UUID at 16 bytes and 36 chars, shortuuid at 16 bytes and 22 chars, Snowflake at 8 bytes and up to 20 chars, MongoID at 12 bytes and 24 chars, and xid at 12 bytes and 20 chars. xid and MongoID are configuration free and sortable, while Snowflake needs machine or data center configuration and a central generator server.
Are xid identifiers cryptographically secure?
No. An xid depends on the system time and a monotonic counter, and the notes say it is not cryptographically secure and should not be used when unpredictability matters. Most other UUID-like implementations share that property; use libraries built on /dev/urandom or crypto/rand if you need random identifiers.
How do I install and use xid in Go?
Run go get github.com/rs/xid, then create an ID with xid.New() and print it with guid.String(), which returns 20 base32hex characters. Embedded information is read back with guid.Machine(), guid.Pid(), guid.Time() and guid.Counter().
How many xid values can one host generate per second?
Uniqueness is guaranteed for 16,777,216 unique IDs per second and per host or process, which comes from the 3 byte counter that occupies 24 bits of the 12 byte value. The generator is lock free, unlike UUIDv1 and UUIDv2.
Official sources
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.
[](https://hysenlabs.com/projects/rs-xid)Star history chart for your README
[](https://hysenlabs.com/projects/rs-xid)Was this useful?