librt.random¶

The librt.random module is part of the librt package on PyPI, and it provides pseudorandom number generation utilities. It can be used as a significantly faster alternative to the stdlib random module in compiled code. It can also be faster than stdlib random in interpreted code, depending on use case.

The module uses the ChaCha8 algorithm with forward secrecy. It is not suitable for cryptographic use, but it provides high-quality, statistically uniform output.

Functions¶

The module provides module-level functions that use thread-local state, so they are safe to call concurrently from multiple threads without external locking, and they scale well even if used from multiple threads:

random() → float¶: Return a random floating-point number in the range [0.0, 1.0).

randint(a: i64, b: i64) → i64¶: Return a random integer n such that a <= n <= b.

randrange(stop: i64, /) → i64¶
randrange(start: i64, stop: i64, /) → i64: Return a random integer from the range. With one argument, the range is [0, stop). With two arguments, the range is [start, stop).

seed(n: i64, /) → None¶: Seed the thread-local random number generator. This only affects module-level functions called from the current thread.

Random class¶

class Random(seed: i64 | None = None)¶

A pseudorandom number generator instance with its own independent state. Use this when you need reproducible sequences or want to avoid interference with the thread-local state used by the module-level functions.

If seed is None, the generator is seeded from OS entropy (via os.urandom()).

It’s not safe to use the same Random instance concurrently from multiple threads without synchronization on free-threaded Python builds.

random() → float¶: Return a random floating-point number in the range [0.0, 1.0).

randint(a: i64, b: i64) → i64¶: Return a random integer n such that a <= n <= b.

randrange(stop: i64, /) → i64¶
randrange(start: i64, stop: i64, /) → i64: Return a random integer from the range. With one argument, the range is [0, stop). With two arguments, the range is [start, stop).

seed(n: i64, /) → None¶: Reseed the generator.

Example¶

Using module-level functions:

from librt.random import randint, seed

def roll_dice() -> i64:
    return randint(1, 6)

Using a Random instance for reproducible sequences:

from librt.random import Random

def generate_data() -> list[i64]:
    rng = Random(42)
    return [rng.randint(0, 100) for _ in range(10)]

Backward compatibility¶

New versions of this module are not guaranteed to generate the same results when using the same seed. A specific seed only produces predictable random numbers on a specific version of librt. In the future we might provide stronger guarantees.