Skip to content

ImageIO

Data & AnalyticsData SciencePython
Official docs ↗GitHub ↗

What it is

ImageIO is a Python library that provides an easy interface to read and write images in a wide range of formats, including PNG, JPEG, BMP, GIF, TIFF, and more. It also supports reading and writing video files and volumetric data.

ImageIO allows you to read, write, and process images and videos using NumPy arrays. It provides a simple API to load images into arrays, perform operations, and save results. Plugins are available for handling different formats and compression options.

Installation

pip install imageio

Getting started

The smallest useful thing you can do with it, and what each part means.

Reading an image
import imageio
img = imageio.imread('example.png')
print(img.shape)
Reads an image from a file and loads it as a NumPy array.
Writing an image
import imageio
imageio.imwrite('output.png', img)
Saves a NumPy array as an image file.

Advanced usage

Where the library earns its place over a simpler alternative.

Reading a video
import imageio
reader = imageio.get_reader('video.mp4')
for frame in reader:
    print(frame.shape)
reader.close()
Reads frames from a video file and prints their dimensions.
Writing a video
import imageio
writer = imageio.get_writer('output.mp4', fps=24)
for frame in frames:  # frames is a list of NumPy arrays
    writer.append_data(frame)
writer.close()
Writes a series of frames (NumPy arrays) to a video file at 24 FPS.
Reading images from URLs
import imageio
img = imageio.imread('https://example.com/image.jpg')
Directly reads an image from a web URL into a NumPy array.
Using plugins for format-specific options
import imageio
img = imageio.imread('example.tiff', format='TIFF')
Specifies a plugin format explicitly when reading an image to handle special format options.

Errors and fixes

The failures you are most likely to hit, and what actually resolves them.

FileNotFoundError
Ensure the file path exists and is accessible.
ValueError: Cannot identify image file
Check that the file format is supported or specify the format explicitly.
RuntimeError: Cannot write frames
Ensure that the writer is opened properly and frames are valid NumPy arrays with correct shape and dtype.

Best practices

  • Use NumPy arrays for all image and video processing for efficiency.
  • Close readers and writers properly to free resources.
  • Specify formats explicitly when needed to avoid ambiguities.
  • Use plugins for advanced format handling (e.g., TIFF, GIF, DICOM).
  • Combine ImageIO with libraries like NumPy, OpenCV, or PIL for processing pipelines.

Background

Why it exists, and what it was reacting to.

ImageIO was developed to unify the reading and writing of images and videos in Python with a simple and consistent API. It is widely used in scientific computing, machine learning, and multimedia applications for processing image and video data.

Related libraries

Others in Data & Analytics for Python.

← All Python librariesPython guide