Python random Module Overview

The random module is a built-in Python module for working with pseudo-random values.

Beginners often use it to:

generate random numbers
choose a random item from a list
shuffle a list
pick several random items

It is useful for games, simple scripts, testing, and practice programs.

It is not the right tool for passwords, secure tokens, or anything security-related. For that, use the secrets module instead.

Quick example

import random

print(random.randint(1, 10))
items = ["apple", "banana", "cherry"]
print(random.choice(items))

Use randint() for a random whole number in a range, and choice() to pick one item from a list.

What the random module is

Python’s random module is part of the standard library, so you do not need to install anything.

It gives you functions for:

random numbers
random choices from sequences
random sampling
shuffling lists

The values are pseudo-random. That means they are produced by an algorithm, but they behave randomly enough for most beginner programs.

Use random for:

small games
classroom examples
simple automation
testing with sample data

Do not use it for:

passwords
authentication tokens
security-sensitive code

When beginners use it most

Beginners usually use random when they want to:

pick a random number in a range
choose a random item from a list
shuffle a list into a new order
pick multiple random items
create simple game behavior

For example, you might:

roll a die
choose a random student name
shuffle quiz questions
build a number guessing game

Functions to know first

These are the most common functions in the random module.

`random.random()`

Returns a floating-point number from 0.0 up to but not including 1.0.

import random

print(random.random())

Possible output:

0.472918374

Use this when you want a random decimal value.

`random.randint(a, b)`

Returns a random whole number from a to b, including both ends.

import random

print(random.randint(1, 6))

Possible output:

This is a common choice for dice rolls and number guessing games.

If you want a deeper explanation, see random.randint() explained.

`random.randrange(start, stop[, step])`

Works like range(), but returns one random value from that range.

import random

print(random.randrange(0, 10))
print(random.randrange(0, 10, 2))

Possible output:

7
4

Important detail:

random.randrange(0, 10) can return 0 through 9
it does not include 10

This is one of the main differences from randint().

`random.choice(seq)`

Returns one random item from a sequence such as a list, tuple, or string.

import random

fruits = ["apple", "banana", "cherry"]
print(random.choice(fruits))

Possible output:

banana

It also works with strings:

import random

print(random.choice("python"))

Possible output:

For more detail, see random.choice() explained.

`random.choices(seq, k=n)`

Returns multiple random items. Values can repeat.

import random

colors = ["red", "blue", "green"]
print(random.choices(colors, k=5))

Possible output:

['blue', 'red', 'blue', 'green', 'blue']

Use this when repeats are allowed.

`random.sample(seq, k=n)`

Returns multiple unique random items.

import random

numbers = [1, 2, 3, 4, 5]
print(random.sample(numbers, k=3))

Possible output:

[5, 2, 1]

Use this when you want random items with no duplicates.

`random.shuffle(x)`

Shuffles a list in place.

import random

data = [1, 2, 3, 4, 5]
random.shuffle(data)
print(data)

Possible output:

[3, 5, 1, 4, 2]

Important: shuffle() changes the original list. It does not create a new one.

For more detail, see random.shuffle() explained.

Important beginner rules

Keep these rules in mind when using random:

Always import the module first with import random
Use choice() only with a non-empty sequence
shuffle() changes the original list
sample() cannot choose more unique items than the sequence contains
randint() includes both the start and end values

Here is a simple example that combines several functions:

import random

names = ["Ana", "Ben", "Cara", "Drew"]

print("Random name:", random.choice(names))
print("Random number:", random.randint(1, 10))
print("Two unique names:", random.sample(names, k=2))

random.shuffle(names)
print("Shuffled list:", names)

Pseudo-random vs truly random

The random module produces values that look random, but they come from a mathematical process.

For most beginner programs, that is completely fine.

Use random for:

games
practice projects
simulations
random test data

Use the secrets module instead for:

passwords
reset links
access tokens
security codes

Common problems and confusion

Here are some common mistakes beginners make with random.

Forgetting to import `random`

If you use random.randint() without importing the module first, you will get a NameError.

print(random.randint(1, 10))

Fix it by adding:

import random

If needed, read how to fix NameError: name is not defined.

Using `choice()` with an empty list

This causes an error because there is nothing to choose.

import random

items = []
print(random.choice(items))

Make sure the sequence is not empty before calling choice().

import random

items = ["apple", "banana"]

if items:
    print(random.choice(items))

Expecting `shuffle()` to return a new list

This is a very common mistake:

import random

my_list = [1, 2, 3]
result = random.shuffle(my_list)
print(result)

Output:

None

Why? Because shuffle() changes the original list directly.

Correct version:

import random

my_list = [1, 2, 3]
random.shuffle(my_list)
print(my_list)

Mixing up `randint()` and `randrange()`

These two functions are similar, but they do not behave exactly the same.

import random

print(random.randint(1, 10))   # can return 10
print(random.randrange(1, 10)) # cannot return 10

This difference can cause off-by-one mistakes.

Common mistakes

These are some beginner mistakes to watch for:

Using random.choice() with an empty list
Writing random(1, 10) instead of random.randint(1, 10)
Assigning result = random.shuffle(my_list) and expecting a shuffled list back
Using random for passwords or secure tokens
Forgetting that randint() includes the end value

If you work with lists a lot, it helps to understand how they behave first. See Python lists explained for beginners.

Useful test commands

You can quickly test the module from the command line:

python --version
python -c "import random; print(random.randint(1, 10))"
python -c "import random; data=[1,2,3]; random.shuffle(data); print(data)"
python -c "import random; print(random.choice(['a','b','c']))"

FAQ

Do I need to install the random module?

No. random is part of Python's standard library.

What is the difference between `randint()` and `randrange()`?

randint(a, b) includes both ends.

randrange() works more like range() and usually excludes the stop value.

Why does `shuffle()` return `None`?

Because it changes the original list directly instead of creating a new one.

Can `random.choice()` work with strings?

Yes. A string is a sequence, so choice() can return one random character.

Should I use `random` for passwords?

No. Use the secrets module for security-related values.