Introduction

Keras does not require image subfolders in every situation. What matters is how labels are obtained. If you want labels inferred from the directory structure, subfolders are required. If labels come from somewhere else, or if you are doing inference only, a flat directory can work perfectly well.

Why Subfolders Matter in Some APIs

Classic helpers such as flow_from_directory() and modern helpers such as image_dataset_from_directory(..., labels="inferred") treat subfolder names as class labels. That means a layout like this is expected:

images/
  cats/
  dogs/

If all files live directly in one folder, there is no class information to infer from the path. So the problem is not that Keras dislikes flat folders. The problem is that folder-based label inference has nothing to infer.

Flat Directory for Inference Only

If you just want predictions and do not need labels, a flat folder is straightforward. In modern TensorFlow, you can load unlabeled data by setting labels=None.

1import tensorflow as tf
2
3dataset = tf.keras.preprocessing.image_dataset_from_directory(
4    "images",
5    labels=None,
6    image_size=(224, 224),
7    batch_size=16,
8    shuffle=False,
9)
10
11predictions = model.predict(dataset, verbose=0)
12print(predictions.shape)

In this mode, the directory structure is ignored. Keras just walks the files and yields image batches.

Flat Directory with Explicit Labels

If you do have labels, you must supply them explicitly instead of asking Keras to infer them from folders. One clean option is a table of filenames and labels.

1from pathlib import Path
2import pandas as pd
3from tensorflow.keras.preprocessing.image import ImageDataGenerator
4
5rows = [
6    {"filename": "cat_1.jpg", "label": "cat"},
7    {"filename": "dog_1.jpg", "label": "dog"},
8    {"filename": "cat_2.jpg", "label": "cat"},
9]
10
11df = pd.DataFrame(rows)
12
13datagen = ImageDataGenerator(rescale=1.0 / 255)
14generator = datagen.flow_from_dataframe(
15    dataframe=df,
16    directory="images",
17    x_col="filename",
18    y_col="label",
19    target_size=(224, 224),
20    class_mode="categorical",
21    batch_size=16,
22    shuffle=True,
23)

This works with a flat folder because the labels come from the dataframe, not from subfolder names.

Modern Alternative: tf.data

For new TensorFlow code, tf.data often gives the most control and scales better than older generator APIs.

1import tensorflow as tf
2
3files = tf.constant([
4    "images/cat_1.jpg",
5    "images/dog_1.jpg",
6    "images/cat_2.jpg",
7])
8labels = tf.constant([0, 1, 0])
9
10def load_example(path, label):
11    image = tf.io.read_file(path)
12    image = tf.image.decode_jpeg(image, channels=3)
13    image = tf.image.resize(image, [224, 224])
14    image = image / 255.0
15    return image, label
16
17dataset = tf.data.Dataset.from_tensor_slices((files, labels))
18dataset = dataset.map(load_example).batch(16).prefetch(tf.data.AUTOTUNE)

This is usually the best route when labels come from CSV files, databases, or filename parsing logic.

Labels from Filenames

If the class is encoded in the filename, build the label table before training.

1from pathlib import Path
2
3paths = sorted(Path("images").glob("*.jpg"))
4labels = [0 if path.name.startswith("cat_") else 1 for path in paths]
5
6for path, label in zip(paths, labels):
7    print(path.name, label)

Once you have paths and labels, you can feed them into tf.data, a dataframe-backed generator, or your own custom loader.

When image_dataset_from_directory Can Still Help

The modern image_dataset_from_directory utility is more flexible than many people realize. If you set labels=None, it works for unlabeled prediction data in a flat folder. If you want labeled supervised training from a flat folder, though, you should usually build a tf.data pipeline or use explicit metadata rather than forcing the directory API to behave like a database.

That distinction is the core answer:

• No subfolders is fine for unlabeled inference
• No subfolders is also fine for training if you provide labels yourself
• No subfolders is not fine for automatic class inference from folder names

Common Pitfalls

One common mistake is calling flow_from_directory() on a flat directory and expecting class labels to be discovered magically. Folder-based generators cannot infer labels that are not encoded in the folder tree.

Another issue is using a flat folder with labels stored elsewhere but never joining the two sources explicitly. Keras needs a clear mapping from each file to its target label.

Developers also sometimes load the entire dataset into RAM just because the folder structure is inconvenient. Streaming with tf.data is usually cleaner and more memory-efficient.

Finally, when labels come from filenames, validate the naming rules. A small inconsistency in filenames can silently poison the training set.

Summary

• Keras does not require image subfolders in every workflow.
• Subfolders are required only when labels are inferred from the directory structure.
• For unlabeled inference, a flat directory works with loaders such as image_dataset_from_directory(..., labels=None).
• For supervised training from a flat directory, provide labels explicitly through metadata or a tf.data pipeline.
• Keep the file-to-label mapping explicit so the training pipeline stays reproducible and debuggable.