← All notes

Summary

ImageFolder loads image collections using their directory layout. Folder names can supply class labels, while metadata files add captions or other fields. [S1]

Details

The documented layout puts class folders under split folders such as train and test. A metadata field named file_name links each row to an image, using a path relative to the metadata file. Label inference has limits: a single flat image directory does not automatically add a label column. Repository-level YAML can define which data files belong to each split. [S1, S2]

Claims

• id: C1 claim: "ImageFolder can infer class labels from directory names." source: S1 evidence: "automatically infers the class labels of your dataset based on the directory name"
• id: C2 claim: "Metadata paths are relative to the directory holding that metadata." source: S1 evidence: "relative path from the directory containing the metadata to the image file"
• id: C3 claim: "The README YAML configs field can assign files to splits." source: S2 evidence: "use the YAML configs field at the top of your README.md"

Sources

• [S1] Create an image dataset. Hugging Face contributors. https://raw.githubusercontent.com/huggingface/datasets/main/docs/source/image_dataset.mdx. Apache-2.0; license: https://raw.githubusercontent.com/huggingface/datasets/main/LICENSE. Accessed 2026-11-05.
• [S2] Structure your repository. Hugging Face contributors. https://raw.githubusercontent.com/huggingface/datasets/main/docs/source/repository_structure.mdx. Apache-2.0; license: https://raw.githubusercontent.com/huggingface/datasets/main/LICENSE. Accessed 2026-11-05.

Attribution and notices

This note is CC BY 4.0. Source material has been condensed and restated; short evidence excerpts retain their source license.

Hugging Face Datasets documentation is Apache-2.0. This note restates the documentation and includes only short evidence excerpts. See the accompanying source license.

@misc{iil_note_d81kapj3,
  author = {{Librarian}},
  title = {{ImageFolder derives labels from folders and joins metadata by file name}},
  howpublished = {iinventedlight Library},
  url = {https://iinventedlight.com/library/notes/hf-datasets-imagefolder/},
  note = {Permanent ID iil:note:d81kapj3. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/hf-datasets-imagefolder.md.