`secrets`

The Python secrets module provides a straightforward and secure way to generate cryptographically strong random numbers suitable for managing sensitive data, such as passwords, account credentials, security tokens, and related secrets.

Here’s a quick example:

>>> import secrets
>>> # Generate a secure random number
>>> secrets.randbelow(10)
4

Key Features

Generates cryptographically secure random numbers
Provides functions to generate secure tokens
Offers functions to compare secrets in a way that reduces the risk of timing attacks

Frequently Used Classes and Functions

Object	Type	Description
`secrets.token_bytes()`	Function	Generates a random byte string
`secrets.token_hex()`	Function	Generates a random text string, in hexadecimal
`secrets.token_urlsafe()`	Function	Generates a random URL-safe text string
`secrets.choice()`	Function	Returns a randomly chosen element from a non-empty sequence
`secrets.randbelow()`	Function	Returns a random int in the range [0, n)
`secrets.randbits()`	Function	Returns a non-negative int with k random bits
`secrets.compare_digest()`	Function	Compares two strings or bytes-like objects in constant time to reduce the risk of timing attacks
`secrets.SystemRandom`	Class	Generates random numbers using the highest-quality sources provided by the operating system
`secrets.DEFAULT_ENTROPY`	Constant	Default number of bytes of randomness used by the module’s `token_*` functions when `nbytes` is omitted or `None`

Examples

Generate a random byte string:

>>> secrets.token_bytes(16)
b'1Y\x80\x10rG \xa9J\xd0\x9c\x9f\x13\xd3\x98\xb1'

Generate a random text string in hexadecimal:

>>> secrets.token_hex(16)
'2befb22f1581dd4ede4821e6252d1359'

Generate a random URL-safe text string:

>>> secrets.token_urlsafe(16)
'JOQrXog1v_aK6QgZp9Lxrg'

Drag the nbytes slider to see how one draw of random bytes looks as token_bytes(), token_hex(), and token_urlsafe() output:

The widget shows one draw encoded three ways, but real token_*() calls each draw fresh bytes, so the three examples above don’t share any bytes. The chips show that nbytes counts bytes of randomness, not characters. At 16, you get 128 bits, which token_hex() spells as 32 chars and token_urlsafe() as 22 chars, because each URL-safe character carries six bits.

Tap a byte or character in any row, or use the arrow keys in the token_bytes() row, to select a byte. It turns yellow in all three rows, where it’s two hex digits and spans two URL-safe characters. Click New draw to get fresh bytes.

Common Use Cases

Generating secure tokens for session management
Creating cryptographically secure passwords
Comparing sensitive data in a secure manner

Real-World Example

Suppose you’re building a web application and need to generate secure tokens for user sessions. Here’s how you can use the secrets module to create a token:

>>> import secrets
>>> token = secrets.token_urlsafe(32)
>>> print(f"Your session token is: {token}")
Your session token is: eMWcxNGqfiucn-SjezajTtOEX7M5D81n3rRL6r06yxM

In this example, the secrets module generates a secure, random URL-safe token suitable for managing user sessions.

Tutorial

Generating Random Data in Python (Guide)

Compare the Python random module with its alternatives for generating random data, on security, versatility, purpose, and speed.

intermediate data-science python

For additional information on related topics, take a look at the following resources:

Generating Random Data in Python (Course)
Generating Random Data in Python (Guide) (Quiz)

Have a question about this? Mentor AI can show you examples, compare related terms, and point you to tutorials.

By Leodanis Pozo Ramos • Updated Oct. 26, 2026

Python Standard Library Share Feedback

secrets