uuid

uuid

A modern, zero-dependency Go UUID library with zero-alloc hot paths, implementing RFC 9562. Built for Go 1.27+ with first-class support for V7 timestamp-ordered UUIDs, pooled generation, and batch APIs.

go get github.com/pscheid92/uuid

Quick Start

import "github.com/pscheid92/uuid"

id := uuid.NewV4()                                       // random UUID
id  = uuid.NewV7()                                       // timestamp-ordered, database-friendly
id, err := uuid.Parse("550e8400-e29b-41d4-a716-446655440000") // parse a string
fmt.Println(id.String())                                  // "550e8400-e29b-41d4-a716-446655440000"

Supported Versions

Usage

Generation

// Random (V4) - most common
id := uuid.NewV4()

// Timestamp-ordered (V7) - recommended for new systems, database-friendly
id := uuid.NewV7()

// Timestamp-ordered at a given time (V7) - backfill existing rows so they sort correctly
id := uuid.NewV7At(row.CreatedAt)

// Deterministic (V5, SHA-1) - same inputs always produce the same UUID
id := uuid.NewV5(uuid.NamespaceDNS, "www.example.com")
// 2ed6657d-e927-568b-95e1-2665a8aea6a2

Parsing & Formatting

Parse is strict - it only accepts the standard 36-character hyphenated form:

id, err := uuid.Parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

ParseLenient additionally accepts URN, braced, and compact forms:

id, _ := uuid.ParseLenient("urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8")
id, _ := uuid.ParseLenient("{6ba7b810-9dad-11d1-80b4-00c04fd430c8}")
id, _ := uuid.ParseLenient("6ba7b8109dad11d180b400c04fd430c8")

MustParse panics on failure, useful for package-level constants:

var myID = uuid.MustParse("550e8400-e29b-41d4-a716-446655440000")

Format back to strings:

id.String() // "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
id.URN()    // "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8"

Serialization

UUID implements encoding.TextMarshaler/TextUnmarshaler (JSON), database/sql.Scanner, and driver.Valuer (SQL). Use a *UUID pointer for nullable fields:

type User struct {
    ID       uuid.UUID  `json:"id"`
    ParentID *uuid.UUID `json:"parent_id"` // null in JSON, SQL NULL when nil
}

// JSON: {"id":"550e8400-e29b-41d4-a716-446655440000","parent_id":null}

var id uuid.UUID
err := row.Scan(&id)

UUIDs are sortable via uuid.Compare (or the Compare method, as in the standard library):

slices.SortFunc(ids, uuid.Compare)

Standard Library Interop

Go 1.27 added a uuid package to the standard library. Both it and this package define UUID as [16]byte, so values convert in either direction at zero cost:

import stdlib "uuid"

id := uuid.UUID(stdlib.New())      // stdlib -> this package
std := stdlib.UUID(uuid.NewV7())   // this package -> stdlib

Use the conversion at API boundaries where a dependency hands you a standard library UUID, and keep this package's type internally for Version, Time, strict parsing, SQL support, and the generation APIs the standard library leaves out.

Why This Library?

Go 1.27 ships a standard library uuid package, and google/uuid and gofrs/uuid have been around for years. The standard library covers V4, V7, lenient parsing, and text encoding with the same [16]byte type as this package, so it is the right choice when that is all you need. This library is for when it is not:

• Everything the standard library leaves out: V5 and V8, Version/Variant/Time accessors, strict Parse, typed ParseError with the offending input, binary marshaling, database/sql Scan/Value, per-instance Generator monotonicity, NewV7At for backfilling, and the Pool and Batch high-throughput paths. Convert between the two types for free (see Standard Library Interop).

• Zero allocations: NewV4, NewV5 (names up to 240 bytes), NewV7, Parse, UnmarshalText, and AppendText all allocate nothing. gofrs/uuid allocates on every generation call except NewV5; google/uuid allocates on every one, except V4 and V7 when its pool is enabled.

• High-throughput APIs: Pool (~14x faster V4, ~2x faster V7) and Batch (~30x faster bulk V4, ~13x bulk V7 at n=100) amortize crypto/rand cost. google/uuid can pool V4 and V7 randomness behind a process-wide toggle (EnableRandPool, not safe to flip while generating), ~1.6–1.8x slower than Pool here; no other library pools or generates in batches.

• V7 monotonicity built-in: Sub-millisecond ordering via RFC 9562 Method 3, with automatic counter fallback. No configuration needed.

• No global configuration: No SetRand, no swappable clock or random source. V4/V5/V8 are stateless. V7 monotonicity lives in a Generator: the package-level NewV7 uses a shared default one (like http.DefaultClient), and you can create your own for isolated ordering.

• Strict by default: Parse accepts only xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Use ParseLenient when you explicitly want URN, braced, or compact forms.

• Simple value type: UUID is [16]byte: comparable, copyable, safe as map key. No NullUUID - use *UUID for nullable SQL/JSON fields.

• Modern Go, zero dependencies: Targets Go 1.27+, uses crypto/rand (infallible), encoding.TextAppender, testing/synctest. Only stdlib. No legacy baggage, no V1/V2/V3/V6.

Further Reading

• Advanced Usage: V7 monotonicity, high-throughput Pool and Batch APIs, properties, namespace constants.
• Internals: V7 bit layout, sub-millisecond precision, monotonic counter fallback, Pool amortization, zero-alloc V5 hashing, parse lookup table.

Benchmarks

Compared to the Go 1.27 standard library uuid package, google/uuid, and gofrs/uuid on Apple M2 (fastest of 8–12 runs; the fastest entry per row is bold):

¹ With google.EnableRandPool(), which also removes the allocation. ² No batch API; the benchmark makes 100 single calls.

All entries for this library and the standard library are zero-alloc except the batches, which allocate their result, and String and MarshalText, which must return a newly allocated result in every library; use AppendText to encode into your own buffer without allocating. Single-call generation is at parity with the standard library and gofrs/uuid (differences of a few ns are run-to-run noise), since all of them read crypto/rand the same way. The text paths take 25–40% less time than the standard library's thanks to lookup-table parsing and an unrolled encoder; google/uuid's parser is within a few percent. google/uuid allocates on every generation call, except V4 and V7 with its pool enabled; gofrs/uuid allocates on every generation call except NewV5. Run the comparison benchmarks yourself:

cd bench && go test -bench=. -benchmem ./...

License

MIT License. See LICENSE for details.