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.
fmt.Println(rand.IntN(6) + 1) // a die roll, different every run
Try it
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.
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
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:IntnbecameIntN,Int31nand friends were replaced by genericN, there is no globalSeedfunction, and the global generator is always randomly seeded. The v1 package still exists but itsSeedis deprecated. - Concurrency: the top-level functions are safe for goroutines and fast. A
*rand.Randyou 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
PCGandChaCha8, which are documented as fixed. - Shuffle uses a Fisher-Yates shuffle in
O(n); for slices,sliceshas no shuffle, so pass a swap function as shown. - Sampling without bias: use
IntN, notInt() % n, which favors small values whenndoes not divide the range evenly. - Tests that depend on random values should create
rand.New(rand.NewPCG(...))with fixed seeds and inject it.