How to generate a UUID in Go

Go has no UUID type in its standard library, so you add one dependency: github.com/google/uuid, where uuid.New() returns a random v4 and uuid.NewV7() returns a time-ordered v7. Every snippet below was run on Go 1.22 with google/uuid v1.6.0.

By the Withuse team · Updated August 27, 2026

The one-liner

import "github.com/google/uuid"

id := uuid.New()
id.String()    // "d0c4eafc-df14-48b3-b373-d8c9d6328491"
id.Version()   // VERSION_4
id.Variant()   // RFC4122

Choosing a version

Every version with google/uuid

uuid.New()                                    // v4, panics on rand failure
uuid.NewRandom()                              // v4, returns (UUID, error)
uuid.NewV7()                                  // v7, returns (UUID, error)
uuid.NewSHA1(uuid.NameSpaceDNS, []byte("example.com"))
                                              // v5 -> cfbff0d1-9375-5685-968c-48ce8b15ae17
uuid.NewMD5(uuid.NameSpaceDNS, []byte("example.com"))
                                              // v3
uuid.NewUUID()                                // v1, returns (UUID, error)

The v5 value above is identical to what Python and JavaScript produce for the same namespace and name — verified across all three. That cross-language agreement is the whole point of the name-based versions.

Trap 1: New() panics, NewRandom() does not

// Panics if crypto/rand fails — fine in main, risky inside a library.
id := uuid.New()

// Explicit: you decide what a failed random source means.
id, err := uuid.NewRandom()
if err != nil {
    return fmt.Errorf("generate id: %w", err)
}

// Panic on purpose, visible at the call site.
id := uuid.Must(uuid.NewRandom())

A failing crypto/rand usually means the process is beyond saving, so New() is reasonable in application code. Avoid it in a library, where a panic crosses an API boundary the caller did not opt into.

Trap 2: the zero value is a valid Nil UUID

var id uuid.UUID          // no error, no nil
fmt.Println(id)           // 00000000-0000-0000-0000-000000000000
fmt.Println(id == uuid.Nil) // true

// Guard explicitly where "unset" is a real state:
if order.ID == uuid.Nil {
    return errors.New("order id is unset")
}

uuid.UUID is a [16]byte array, so it has a zero value rather than a nil one. An unpopulated struct field, a JSON payload missing the key, or a scanned NULL column all silently become the Nil UUID. When absent and zero genuinely differ in your domain, use a *uuid.UUID field.

UUID v7 and its timestamp

v7, _ := uuid.NewV7()
// 01a041d3-3631-7b71-b418-a2a466963cbb

sec, nsec := v7.Time().UnixTime()
time.Unix(sec, nsec).UTC()   // 2026-08-27T06:05:56.145Z — the creation time

Values generated inside the same millisecond still sort correctly: google/uuid increments a counter in the random field rather than redrawing it, which we confirmed by generating three in a tight loop and checking their string order. That property is what makes v7 useful as a primary key — see UUID v4 vs v7 for the index reasoning.

Library comparison

Avoid satori/go.uuid: it is unmaintained and once shipped an incompatible API change under the same import path, which broke builds that had not pinned a version.

Storing UUIDs with pgx

// PostgreSQL: use the native uuid column type (16 bytes, not 36 chars).
_, err := pool.Exec(ctx,
    "INSERT INTO orders (id, total) VALUES ($1, $2)",
    uuid.Must(uuid.NewV7()), total)

// Scanning back
var id uuid.UUID
err = pool.QueryRow(ctx, "SELECT id FROM orders WHERE ...").Scan(&id)

pgx handles uuid.UUID natively. With database/sql, google/uuid already implements sql.Scanner and driver.Valuer, so the type works there too. Column-type guidance lives in the PostgreSQL guide.

Frequently asked questions

Need sample UUIDs for a Go test fixture? Generate up to 1,000 at once with our free UUID generator. Also in this series: UUID in Java · collision probability