TensorFlow · Module

Dataset.shuffle

Randomly shuffles dataset elements using a finite sampling buffer. A buffer at least as large as the dataset is needed for perfect shuffling, while smaller buffers use less memory but provide less thorough mixing.

How it works

The method returns a dataset that draws elements through a random buffer. It fills that buffer with up to the requested number of elements, samples from it, and replaces selected entries with later elements; a buffer at least as large as the dataset is needed for perfect shuffling.

Syntax

shuffle(buffer_size, seed=None, reshuffle_each_iteration=None, name=None) -> 'DatasetV2'

Parameters

Name	Type	Description
`buffer_size`	`tf.int64 scalar tf.Tensor`	A tf.int64 scalar tensor specifying how many elements the new dataset samples from; using the dataset cardinality gives uniform full-dataset shuffling.
`seed`	`tf.int64 scalar tf.Tensor`	Optional tf.int64 scalar tensor used to create the random distribution; TensorFlow's random-seed behavior applies.
`reshuffle_each_iteration`	`bool`	Optional boolean controlling whether the dataset is pseudorandomly reshuffled on every iteration; defaults to true.
`name`	`string`	Optional name for the tf.data operation.

Returns

A DatasetV2 containing the elements of the input dataset in shuffled order.

Key points

The operation produces another dataset whose element order is randomized.
Shuffling begins by filling an internal buffer up to the requested capacity.
Each next output is selected randomly from the currently populated buffer.
After an element is selected, the buffer can be replenished with later input elements.
Uniform full-dataset randomization requires a buffer no smaller than the complete dataset.
For a finite dataset that fits in memory, its cardinality can be used as the buffer size for uniform shuffling.

Common mistakes

Using the dataset cardinality as the buffer size can exhaust memory when the complete dataset does not fit in memory.
If reshuffle_each_iteration is omitted, the dataset is pseudorandomly reshuffled on each iteration.

Example: Shuffle a dataset deterministically

import tensorflow as tf

dataset = tf.data.Dataset.range(3)
shuffled = dataset.shuffle(3, seed=7, reshuffle_each_iteration=False)
print(list(shuffled.as_numpy_iterator()))

Creates a finite dataset, shuffles it using a full-size buffer, and keeps the same order across repeated iterations.

When to use it

Reduce order-related bias

Training input pipelines

Uniformly permute all elements

Small finite datasets

Shuffle with bounded memory

Large datasets

Interview questions

QHow does Dataset.shuffle work internally?

shuffle creates a new dataset whose elements are randomized through a buffer. The buffer is populated and then sampled from, with consumed entries replaced by subsequent dataset elements.

Follow-up: What buffer size gives a uniform permutation? A buffer at least as large as the entire dataset; for a finite dataset, its cardinality is the documented choice.

QWhat does buffer_size control?

buffer_size controls how many dataset elements are available for sampling and therefore how thoroughly the stream is mixed. A full-size buffer is required for perfect shuffling.

Follow-up: What trade-off follows from a larger buffer? It improves shuffle quality but can increase memory use, so a full-dataset buffer is unsuitable for datasets that exceed available memory.

QHow do seed and reshuffle_each_iteration affect repeatability?

reshuffle_each_iteration determines whether the dataset receives a new pseudorandom order each time it is iterated. It defaults to True; setting it to False preserves the shuffle order for repeated iterations when the seed and dataset setup are unchanged.

Follow-up: How can an experiment make iteration order repeatable? Provide a seed and disable reshuffling between iterations.

tf.data.Dataset.range
tf.data.Dataset.batch
tf.data.Dataset.repeat
tf.random.set_seed

Source: tf.data.Dataset. Checked 2026-10-15.