Crates and features

The Rand library consists of a family of crates. The rand crate provides the main user-interface; where additional distributions are required, the rand_distr or statrs crate may be used in addition.

The library contains several building blocks: getrandom interfaces with the platform-dependent random number source, rand_core defines the API that generators must implement, and a number of crates like rand_chacha and rand_xoshiro provide pseudo-random generators.

getrandom ┐
          └ rand_core ┐
                      ├ rand_chacha ┐
                      ├ rand_hc     ┤
                      ├ rand_pcg    ┤
                      └─────────────┴ rand ┐
                                           ├ rand_distr
                                           └ statrs

Feature flags

Rand crates allow some configuration via feature flags. Check the READMEs of individual crates for details.

No-std support is available across most Rand crates by disabling default features: rand = { version = "0.7", default-features = false }. This is affected by the following flags:

  • std opts-in to functionality dependent on the std lib
  • alloc (implied by std) enables functionality requiring an allocator (when using this feature in no_std, Rand requires Rustc version 1.36 or greater)

Some Rand crates can be built with support for the following third-party crates:

  • log enables a few log messages via log
  • serde1 enables serialization via serde, version 1.0

Note that cryptographic RNGs do not support serialisation since this could be a security risk. If you need state-restore functionality on a cryptographic RNG, the ChaCha generator supports getting and setting the stream position, which, together with the seed, can be used to reconstruct the generator's state.

WASM support

Almost all Rand crates support WASM out of the box. Only the rand_core crate may require enabling features for WASM support. Consequently, if you are using another crate depending on rand_core (such as most Rand crates), you may have to explicitly enable getrandom features for it to work.