Environment:Huggingface Datasets Image Dependencies

Knowledge Sources	HuggingFace Datasets
Domains	Image Processing, Computer Vision, Media Encoding, Media Decoding
Last Updated	2026-02-14 19:00 GMT

Overview

Description

The Image Dependencies environment defines the optional packages required to enable image encoding and decoding within the HuggingFace Datasets library. Image support relies on Pillow (the PIL fork), which is the standard Python library for opening, manipulating, and saving image files. Pillow is not included in the base datasets installation and must be installed separately or via the [vision] extra.

Usage

Image features are activated by installing the optional [vision] extra. This unlocks the ability to:

• Encode image data into dataset-compatible formats via image.py
• Decode image data from stored representations via image.py
• Access EXIF metadata and other image properties through PIL's API

The library checks for the availability of Pillow at runtime using importlib.util.find_spec("PIL") and stores the result in the PIL_AVAILABLE flag defined in config.py.

System Requirements

• Python: Compatible with the Python versions supported by HuggingFace Datasets
• Operating System: Linux, macOS, or Windows
• System Libraries: Pillow may require system-level imaging libraries (e.g., libjpeg, libpng, zlib) depending on the image formats used

Dependencies

Package	Minimum Version	Purpose	Required By
Pillow	9.4.0	Image encoding, decoding, and manipulation	image.py

As defined in setup.py:

VISION_REQUIRE = ["Pillow>=9.4.0"]

The minimum version of Pillow 9.4.0 was chosen because this is when PIL.Image.ExifTags was introduced, which the datasets library uses for EXIF metadata handling.

Credentials

No credentials are required to install or use the image dependencies. All packages are available from public PyPI repositories.

Quick Install

Install the vision extras with pip:

pip install datasets[vision]

Or install the dependency directly:

pip install "Pillow>=9.4.0"

Code Evidence

Runtime availability check in config.py:

PIL_AVAILABLE = importlib.util.find_spec("PIL") is not None

Image encoding guard in image.py:

# Raises an error when Pillow is not installed
"To support encoding images, please install 'Pillow'."

Image decoding guard in image.py:

# Raises an error when Pillow is not installed
"To support decoding images, please install 'Pillow'."

Version requirement rationale in setup.py:

VISION_REQUIRE = ["Pillow>=9.4.0"]  # When PIL.Image.ExifTags was introduced

Common Errors

Error Message	Cause	Resolution
To support encoding images, please install 'Pillow'.	Pillow is not installed and image encoding was attempted	Run pip install "Pillow>=9.4.0"
To support decoding images, please install 'Pillow'.	Pillow is not installed and image decoding was attempted	Run pip install "Pillow>=9.4.0"
ModuleNotFoundError: No module named 'PIL'	Pillow package is missing from the environment	Run pip install "Pillow>=9.4.0"
ImportError: cannot import name 'ExifTags' from 'PIL.Image'	Installed Pillow version is older than 9.4.0	Run pip install --upgrade "Pillow>=9.4.0"

Compatibility Notes

• The Pillow >= 9.4.0 requirement is specifically tied to the introduction of PIL.Image.ExifTags. Earlier Pillow versions will not provide full functionality.
• Pillow is imported under the PIL namespace (the original Python Imaging Library name), which is why the availability check uses find_spec("PIL") rather than find_spec("Pillow").
• The PIL_AVAILABLE flag in config.py allows the library to gracefully degrade when Pillow is absent, rather than failing at import time.
• Pillow supports a wide range of image formats (JPEG, PNG, TIFF, BMP, GIF, WebP, etc.), but some formats may require additional system libraries to be installed.

Related Pages

• Huggingface_Datasets_Image — Image feature type implementation