Implementation:Huggingface Datasets ImageFolder Builder

Knowledge Sources	Huggingface Datasets HF Datasets Docs
Domains	Data_Loading, Computer_Vision
Last Updated	2026-02-14 18:00 GMT

Overview

Folder-based dataset builder for loading image files organized in directories provided by the HuggingFace Datasets library.

Description

ImageFolder is a packaged dataset builder extending FolderBasedBuilder that loads image datasets from directory structures. It sets BASE_FEATURE = datasets.Image and BASE_COLUMN_NAME = "image", meaning each loaded file is treated as an image and placed in an "image" column. The companion ImageFolderConfig extends FolderBasedBuilderConfig with two optional boolean fields: drop_labels and drop_metadata, which control whether automatic label inference from folder names and metadata file loading are disabled.

The builder supports a comprehensive list of image file extensions derived from PIL (Pillow), including common formats such as .png, .jpg, .jpeg, .gif, .bmp, .tiff, .webp, and many others (62 extensions total). This extension list is statically defined to avoid requiring Pillow at import time and to ensure deterministic behavior.

Usage

Use ImageFolder via load_dataset("imagefolder", data_dir=...) to load image datasets from a directory. Subdirectory names are automatically used as labels unless drop_labels=True is set. Metadata files (e.g., metadata.csv or metadata.jsonl) in the data directory are parsed for additional columns unless drop_metadata=True.

Code Reference

Source Location

Repository: datasets
File: src/datasets/packaged_modules/imagefolder/imagefolder.py
Lines: 1-103

Signature

class ImageFolderConfig(folder_based_builder.FolderBasedBuilderConfig):
    """BuilderConfig for ImageFolder."""
    drop_labels: bool = None
    drop_metadata: bool = None


class ImageFolder(folder_based_builder.FolderBasedBuilder):
    BASE_FEATURE = datasets.Image
    BASE_COLUMN_NAME = "image"
    BUILDER_CONFIG_CLASS = ImageFolderConfig
    EXTENSIONS: list[str]  # set to IMAGE_EXTENSIONS at module level

Import

from datasets.packaged_modules.imagefolder.imagefolder import ImageFolder, ImageFolderConfig

I/O Contract

Inputs (ImageFolderConfig)

Name	Type	Required	Description
data_dir	`str`	Yes	Path to the root directory containing image files, optionally organized into subdirectories for label inference.
drop_labels	`bool`	No	If True, disables automatic label inference from subdirectory names. Defaults to None (auto-detect).
drop_metadata	`bool`	No	If True, disables loading of metadata files (`metadata.csv`, `metadata.jsonl`). Defaults to None (auto-detect).

Outputs

Name	Type	Description
dataset	`Dataset`	An Arrow-backed Dataset with an `"image"` column of type `datasets.Image`, and optionally a `"label"` column and/or additional metadata columns.

Supported Extensions

The builder recognizes 62 image file extensions, including:

.png, .jpg, .jpeg, .gif, .bmp, .tiff, .tif, .webp, .ico, .psd, .jp2, .pbm, .pgm, .ppm, .tga, and many more.

Usage Examples

Basic Usage

from datasets import load_dataset

# Load images from a directory with subdirectory-based labels
# data_dir/
#   cats/
#     cat1.jpg
#     cat2.jpg
#   dogs/
#     dog1.jpg
#     dog2.jpg
ds = load_dataset("imagefolder", data_dir="path/to/data_dir", split="train")
print(ds[0])  # {"image": <PIL.Image>, "label": 0}
print(ds.features["label"].names)  # ["cats", "dogs"]

Without Labels

from datasets import load_dataset

# Load images without label inference
ds = load_dataset("imagefolder", data_dir="path/to/images", drop_labels=True, split="train")
print(ds.column_names)  # ["image"]

Related Pages

Implements Principle

Principle:Huggingface_Datasets_ImageFolder_Dataset_Building

Requires Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment