Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Time, Math and Randomness

Go math/rand/v2 package

Reference for Go math/rand/v2: IntN, N, Float64, Perm, Shuffle, seeded PCG and ChaCha8 generators, reproducible sequences and when to use crypto/rand.

The package math/rand/v2 (Go 1.22 and later) generates pseudo-random numbers. Top-level functions such as rand.IntN(n), rand.Float64() and rand.Shuffle use a global generator that is seeded randomly at program start, so each run differs and you never need to seed it yourself.

When you need a repeatable sequence, for tests, simulations or games with shareable seeds, create your own generator with rand.New(rand.NewPCG(seed1, seed2)). The same seeds always give the same numbers.

Go
fmt.Println(rand.IntN(6) + 1) // a die roll, different every run

Try it

Go Reproducible numbers with a seeded generator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go Global functions: checking ranges, not values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
func IntN(n int) int           // [0, n), panics if n <= 0
func Int64N(n int64) int64
func N[Int intType](n Int) Int // generic, any integer type or Duration
func Int() int                 // non-negative
func Uint64() uint64
func Float64() float64         // [0.0, 1.0)
func NormFloat64() float64     // standard normal distribution
func ExpFloat64() float64      // exponential distribution
func Perm(n int) []int
func Shuffle(n int, swap func(i, j int))

func New(src Source) *Rand
func NewPCG(seed1, seed2 uint64) *PCG
func NewChaCha8(seed [32]byte) *ChaCha8
Name Description
n Exclusive upper bound; must be positive or the call panics.
swap Called by Shuffle to exchange elements i and j.
src A Source (generator state): PCG is small and fast, ChaCha8 is cryptographic-quality but not meant for secrets.

Returns: a number in the stated range. The *Rand methods have the same names as the top-level functions.

Usage notes

  • Not for secrets. Passwords, tokens, session IDs and keys must use crypto/rand. Predictable generators can be reverse engineered from their output.
  • Differences from the old math/rand: Intn became IntN, Int31n and friends were replaced by generic N, there is no global Seed function, and the global generator is always randomly seeded. The v1 package still exists but its Seed is deprecated.
  • Concurrency: the top-level functions are safe for goroutines and fast. A *rand.Rand you create is not safe to share; give each goroutine its own or protect it with a mutex.
  • Reproducibility: the sequence for a given seed is stable for a given generator algorithm, but treat it as stable across Go versions only for PCG and ChaCha8, which are documented as fixed.
  • Shuffle uses a Fisher-Yates shuffle in O(n); for slices, slices has no shuffle, so pass a swap function as shown.
  • Sampling without bias: use IntN, not Int() % n, which favors small values when n does not divide the range evenly.
  • Tests that depend on random values should create rand.New(rand.NewPCG(...)) with fixed seeds and inject it.