NumPy Random Seeds — Global Overwrite Ruins Reproducibility

NumPy's global random seed is a reproducibility landmine in multi-module codebases. Two libraries calling np.random.seed() independently can cause ±3% validation accuracy swings on the same seed. The fix is the Generator API with explicit, isolated instances. This article shows how to eliminate cross-contamination and make your random streams deterministic in production.

Why NumPy Random Seeds Are a Global Trap

The numpy.random module provides pseudorandom number generation (PRNG) via algorithms like PCG64 and MT19937. Its core mechanic: a global, mutable RandomState object shared across all calls to functions like rand, randn, and shuffle. Setting numpy.random.seed(42) overwrites that global state, forcing every subsequent random call in the same process to follow the same deterministic sequence — including calls from imported libraries you don't control.

This global design means any code path that calls seed() resets the generator for the entire process. In practice, two independent modules both calling seed() at different times will interfere: the second call destroys the first's reproducibility. The generator itself is a finite-state machine with 2^19937-1 period for MT19937, but the seed only selects one of 2^32 starting states. That's 4 billion possible sequences — enough for most work, but not cryptographically secure.

Use numpy.random when you need fast, reproducible randomness for simulations, data shuffling, or weight initialization — but only in isolated scripts or notebooks. In production systems with multiple components, the global state is a liability. Prefer numpy.random.Generator (new in 1.17) with explicit local instances to avoid cross-module contamination. The old API remains for backward compatibility, but treat it as a landmine in multi-module codebases.

The Modern Generator API

Create a generator with np.random.default_rng(). Pass a seed for reproducibility. The generator object is independent — you can have multiple generators with different seeds without interference. Use it for all subsequent random operations.

import numpy as np

# Reproducible — same seed gives same numbers every run
rng = np.random.default_rng(seed=42)

print(rng.random(5))          # 5 floats in [0, 1)
print(rng.integers(0, 10, 5)) # 5 ints in [0, 10)
print(rng.normal(0, 1, 5))    # 5 standard normal samples
print(rng.uniform(2.0, 5.0, 3)) # 3 floats in [2, 5)

Common Distributions

The Generator API supports all standard distributions: normal, binomial, poisson, exponential, uniform, and more. Each distribution function accepts shape parameters and a size argument to produce arrays.

import numpy as np
rng = np.random.default_rng(0)

# Normal (Gaussian)
print(rng.normal(loc=170, scale=10, size=5))  # heights in cm

# Binomial — n trials, p probability
print(rng.binomial(n=10, p=0.5, size=5))  # coin flips

# Poisson — events per interval
print(rng.poisson(lam=3, size=5))

# Exponential — time between events
print(rng.exponential(scale=1.0, size=5))

Shuffling and Sampling

Shuffle arrays in place with rng.shuffle() or get a permuted copy with rng.permutation(). For random sampling from an array without replacement, use rng.choice(replace=False). For bootstrap sampling, set replace=True.

import numpy as np
rng = np.random.default_rng(42)

arr = np.arange(10)

# Shuffle in place
rng.shuffle(arr)
print(arr)  # [0 3 7 2 5 1 9 4 6 8] — order varies

# Sample without replacement
print(rng.choice(arr, size=3, replace=False))

# Sample with replacement (bootstrap)
print(rng.choice(arr, size=5, replace=True))

# Permutation — returns a copy, does not modify original
orig = np.arange(5)
shuffled = rng.permutation(orig)
print(orig)     # [0 1 2 3 4] — unchanged
print(shuffled) # shuffled copy

Seeding Strategies and Reproducibility

Seeding controls the initial state of the generator. For reproducibility, use a fixed integer seed. For distributed systems, ensure each process gets a unique but reproducible seed (e.g., based on process rank). For testing, consider using a seed derived from the test name to isolate test randomness.

import numpy as np
from hashlib import sha256

# Good: fixed seed
rng = np.random.default_rng(seed=42)

# Better: unique seed per process (e.g., MPI rank)
process_id = 0  # from MPI
seed = int(sha256(b"my_experiment").hexdigest(), 16) + process_id
rng_rank = np.random.default_rng(seed)

# Testing: seed from test name
def my_test_function():
    test_seed = int(sha256(b"my_test_function").hexdigest(), 16) % 2**32
    rng_local = np.random.default_rng(test_seed)
    # ... use rng_local

Performance Considerations and Vectorisation

Generator API is vectorised — always generate arrays of samples in one call rather than looping. The performance gain is 10-100x for large sizes. Additionally, use dtype parameters for integer and float precision to control memory and speed.

import numpy as np
import time

rng = np.random.default_rng(0)

# Slow: loop
start = time.time()
for _ in range(100000):
    rng.random()
print("Loop time:", time.time() - start)

# Fast: vectorised
start = time.time()
rng.random(100000)
print("Vectorised time:", time.time() - start)

replace=True Is a Data Leak Waiting to Happen

Most devs treat replace=False as the default. It isn't. NumPy's choice() defaults to replace=True, meaning you can silently sample the same element multiple times. In production, this duplicates data points, inflates confidence intervals, and corrupts train/test splits.

The fix is one keyword argument, but the mindset shift matters more: always declare replace explicitly. Never rely on defaults when sampling from a finite population. If you're bootstrapping, replace=True is correct. If you're building a validation set, replace=False is your only option.

The WHY is simple: replacement sampling creates statistical dependencies between samples. Non-replacement sampling preserves the underlying distribution's independence assumptions. Choose wrong, and your metrics lie to you.

// io.thecodeforge — python tutorial

import numpy as np

sensor_readings = np.array([12.4, 13.1, 11.8, 12.9, 13.0, 11.5])

// Default: replace=True — you can get duplicates
bad_val = np.random.choice(sensor_readings, size=3)
print(bad_val)  // e.g., [12.4 12.4 13.1]

// Explicit non-replacement — guarantees distinct samples
val_set = np.random.choice(sensor_readings, size=3, replace=False)
print(val_set)  // e.g., [12.4 11.5 13.0]

shuffle() vs. permutation() — One Mutates Your Data, the Other Doesn't

Choosing between shuffle() and permutation() is a memory vs. clarity trade-off. shuffle() modifies the array in-place. Zero memory overhead, but it destroys the original ordering. permutation() returns a newly shuffled copy, leaving the original untouched. Costs memory and a copy.

In production data pipelines, in-place mutation is dangerous. If another process references that array, you've silently corrupted its view. I've seen this cause non-deterministic test failures that took days to trace back to a shuffle() call buried in a helper function.

The rule: use permutation() unless you're CPU-bound and can guarantee no other reference exists. If you must use shuffle(), document it with a comment that screams "MUTATES IN PLACE — NO OTHER REFERENCES."

// io.thecodeforge — python tutorial

import numpy as np

batch_ids = np.array([101, 102, 103, 104, 105])
original_order = batch_ids.copy()

// shuffle() mutates original array
np.random.shuffle(batch_ids)
print(batch_ids)  // e.g., [105, 102, 104, 101, 103]
print(original_order)  // still [101, 102, 103, 104, 105]

// permutation() returns new array, leaves original alone
restored = np.random.permutation(original_order)
print(restored)     // e.g., [103, 101, 105, 102, 104]
print(original_order)  // unchanged: [101, 102, 103, 104, 105]