Implementation:Huggingface Datasets Image

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

Overview

Concrete tool for handling image data in datasets with encoding and decoding support provided by the HuggingFace Datasets library.

Description

Image is a dataclass feature type for image data. It accepts multiple input formats: absolute file paths (str or pathlib.Path), dictionaries with "path" and "bytes" keys (for embedded images in Parquet/Webdataset), NumPy arrays, or PIL.Image.Image objects. Images are stored in Arrow as a struct with bytes (binary) and path (string) fields. When decoded (default), accessing image data returns PIL.Image.Image objects. An optional mode parameter converts images to a specific mode (e.g., "RGB", "L"). Setting decode=False returns the raw path/bytes dictionary.

Usage

Use Image as a feature type for any column containing image data. Cast existing columns with dataset.cast_column("col", Image()) or specify it in the Features schema during dataset construction.

Code Reference

Source Location

Repository: datasets
File: src/datasets/features/image.py
Lines: 47-315

Signature

@dataclass
class Image:
    mode: Optional[str] = None
    decode: bool = True
    id: Optional[str] = field(default=None, repr=False)
    # Automatically constructed
    dtype: ClassVar[str] = "PIL.Image.Image"
    pa_type: ClassVar[Any] = pa.struct({"bytes": pa.binary(), "path": pa.string()})
    _type: str = field(default="Image", init=False, repr=False)

Import

from datasets import Image

I/O Contract

Inputs

Name	Type	Required	Description
mode	`str`	No	PIL image mode to convert to (e.g., "RGB", "L"). None uses native mode.
decode	`bool`	No	Whether to decode image data on access. Defaults to True.
id	`str`	No	Optional feature identifier.

Outputs

Name	Type	Description
instance	`Image`	An Image feature type for use in Features schemas.

Usage Examples

Basic Usage

from datasets import Dataset, Image, Features, Value

# Create dataset with image paths
ds = Dataset.from_dict(
    {"image": ["path/to/image1.jpg", "path/to/image2.jpg"]},
    features=Features({"image": Image()}),
)

# Access returns PIL Image objects
# img = ds[0]["image"]  # <PIL.JpegImagePlugin.JpegImageFile ...>

# Disable decoding for raw path/bytes access
ds_raw = ds.cast_column("image", Image(decode=False))

Related Pages

Implements Principle

Principle:Huggingface_Datasets_Image_Feature_Handling

Requires Environment

Page Connections

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

Principle

Implementation

Heuristic

Environment