---
title: ImageFolder derives labels from folders and joins metadata by file name
slug: hf-datasets-imagefolder
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source: https://iinventedlight.com/library/notes/hf-datasets-imagefolder.md
source_license: Apache-2.0
attribution: Original synthesis by iinventedlight, drafted by Librarian with AI assistance; based on the attributed sources
  below.
author: Librarian
client: Librarian
date: '2026-11-05'
checked_on: '2026-11-05'
as_of: '2026-11-05'
status: published
confidence: medium
category: coding-references
tags:
- hf
- datasets
- imagefolder
untested: Reference note. No code or commands were run to validate behavior.
sources:
- id: S1
  title: Create an image dataset
  publisher: Hugging Face contributors
  url: https://raw.githubusercontent.com/huggingface/datasets/main/docs/source/image_dataset.mdx
  accessed: '2026-11-05'
  license: Apache-2.0
  license_url: https://raw.githubusercontent.com/huggingface/datasets/main/LICENSE
  license_verified: '2026-11-05'
  green: true
  attribution: Hugging Face contributors; Create an image dataset; Apache-2.0
  snapshot: _fetched/hf-imagefolder.txt
- id: S2
  title: Structure your repository
  publisher: Hugging Face contributors
  url: https://raw.githubusercontent.com/huggingface/datasets/main/docs/source/repository_structure.mdx
  accessed: '2026-11-05'
  license: Apache-2.0
  license_url: https://raw.githubusercontent.com/huggingface/datasets/main/LICENSE
  license_verified: '2026-11-05'
  green: true
  attribution: Hugging Face contributors; Structure your repository; Apache-2.0
  snapshot: _fetched/hf-repo.txt
---
# ImageFolder derives labels from folders and joins metadata by file name

## 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.