Python random Module

3Python random: explained step by step

The numbers from random are not truly random. They come from a formula that starts from a number called the seed, and that is a feature: if you start from the same seed, you get exactly the same "random" sequence again. Games leave the seed alone so every play is different. Tests, simulations and tutorials fix it so results can be repeated. Every snippet on this page calls random.seed(...) first, so what you see is what you get.

Seeding: same seed, same numbers

random.seed(42) puts the generator into a known starting state. Seed again with the same value and the sequence starts over.

import random

random.seed(42)
print(random.random(), random.random())

random.seed(42)
print(random.random())

Seed once, at the start of the program. Seeding again inside a loop restarts the sequence every time (see the mistakes below). Without a call to seed, Python seeds itself from the operating system, so each run differs.

Numbers: random, uniform, randint, randrange

import random

random.seed(1)
print(random.random())
print(random.uniform(10, 20))
print(random.randint(1, 6))
print(random.randrange(0, 10, 2))

random() gives a float from 0 up to (not including) 1, and uniform(a, b) a float between a and b. For whole numbers there are two near-twins. randint(a, b) includes both ends, so randint(1, 6) is a die. randrange(a, b) works like range() and stops before b; a third argument sets the step, so randrange(0, 10, 2) is one of 0, 2, 4, 6, 8. To pick a position in a list, use randrange(len(items)).

Picking from a list: choice, choices, sample

• choice(items) returns one item, and raises IndexError on an empty list.
• choices(items, k=3) draws 3 items with replacement, like putting each card back, so repeats can happen. It always returns a list, even for k=1, and accepts weights= to make some items likelier.
• sample(items, 3) draws 3 items without replacement, like dealing cards: nothing appears twice. Asking for more items than the list holds is a ValueError.

import random

random.seed(3)
colors = ["red", "green", "blue", "gold"]
print(random.choice(colors))
print(random.choices(colors, k=5))
print(random.choices(colors, weights=[10, 1, 1, 1], k=5))
print(random.sample(colors, 2))

Use choices for independent events (a weighted loot drop) and sample for winners, teams or a hand of cards.

shuffle: reorder a list in place

random.shuffle(items) rearranges the list itself and returns None. Do not assign its result. It needs a mutable list, so a tuple fails with a TypeError. When you need the original order as well, copy first, or use sample(items, k=len(items)), which returns a new shuffled list.

import random

random.seed(8)
deck = ["A", "K", "Q", "J"]
original = list(deck)
result = random.shuffle(deck)
print(result)
print(deck, original)
print(random.sample(original, k=len(original)))

Your own generator: random.Random(seed)

The functions above share one hidden generator. If two parts of a program both draw from it, they disturb each other's sequence. random.Random(seed) creates a private generator with the same methods (randint, choice, shuffle and the rest) and its own state.

import random

dice = random.Random(10)
cards = random.Random(10)
print([dice.randint(1, 6) for _ in range(5)])
print([cards.randint(1, 6) for _ in range(5)])

rng = random.Random(5)
first = rng.randint(1, 100)
random.random()
second = rng.randint(1, 100)
check = random.Random(5)
print([first, second] == [check.randint(1, 100), check.randint(1, 100)])

The same seed gives the same stream, and drawing from the shared generator in between changes nothing. That makes a private generator the right choice for a function that must be reproducible, such as a test-data builder.

Simulations: dice, coins and events

Put a draw in a loop and you have a simulation. A coin flip is choice(["heads", "tails"]), and an event with a 25% chance is rng.random() < 0.25.

import random

rng = random.Random(7)
rolls = [rng.randint(1, 6) for _ in range(600)]
for face in range(1, 7):
    print(face, rolls.count(face))
hits = sum(rng.random() < 0.25 for _ in range(1000))
print("Events at 25%:", hits, "out of 1000")

The counts are near 100 each, never exactly 100. More trials land closer to the expected share. A guessing game follows the same pattern: draw secret = rng.randint(1, 100) once, then compare each guess with it.

Passwords and tokens: use secrets

random is predictable: whoever learns the seed, or enough outputs, can work out what comes next. For passwords, reset links and API tokens use the secrets module. It draws from the operating system's secure source and cannot be seeded, so its results can never be reproduced.

import secrets

token = secrets.token_hex(8)
pin = "".join(secrets.choice("0123456789") for _ in range(6))
print(len(token), len(pin), pin.isdigit())

Only the lengths are printed because the values change on every run, and a real secret should never be printed or logged.

Which one should I use?

Use random for games, simulations and sample data, with a seed when you need repeatable results. Use secrets for anything an attacker would like to guess.