Imageio

2.37.3 · active · verified Sat Mar 28

Imageio is a mature Python library (current version 2.37.3) that makes it easy to read and write image and video data. This includes animated images, video, volumetric data, and scientific formats. It is cross-platform, runs on Python 3.10+, and is easy to install. The library is actively maintained with a focus on ease of use and broad format support.

Warnings

breaking The core API of Imageio underwent a significant overhaul with the introduction of `v3`. The older API, previously accessible directly under the `imageio` namespace (e.g., `imageio.imread`), is now considered `imageio.v2` and is deprecated.
Fix: Migrate your code to use `import imageio.v3 as iio` and call functions like `iio.imread()` or `iio.imwrite()`. The `imageio.v2` namespace is not actively versioned, meaning breaking changes may occur there without minor version bumps.
gotcha For reading and writing video files (e.g., MP4, AVI), Imageio requires an external plugin like `imageio-ffmpeg` or `pyav`. Without one of these optional dependencies, video operations will fail (e.g., `iio.imread('video.mp4')` will raise a `PluginNotFoundError`).
Fix: Install the necessary video backend: `pip install imageio-ffmpeg` (recommended for most users as it bundles FFmpeg) or `pip install pyav`.
gotcha While Pillow is a required dependency for common image formats, users occasionally encounter issues where Imageio's Pillow plugin cannot be found or loaded, leading to errors when processing common image types (JPEG, PNG). This often stems from environment misconfigurations.
Fix: Ensure Pillow is correctly installed and accessible within your active Python environment. This can be problematic when mixing package managers (e.g., `pip` and `conda`) or managing multiple Python installations. Verify `pip show Pillow` shows the correct installation for your current environment.

Install

pip install imageio PyPI

Imports

iio
```
import imageio.v3 as iio
```
The modern and recommended API is accessed via `imageio.v3`. Importing it as `iio` is the standard convention. Direct imports from the root `imageio` namespace use the older, deprecated v2 API.

Quickstart

This example demonstrates how to read an image using a built-in sample URI, convert it to grayscale using NumPy, and save the modified image to a new file. It utilizes the recommended `imageio.v3` API.

import imageio.v3 as iio
import numpy as np

# Read a standard image from imageio's sample data
im = iio.imread('imageio:chelsea.png')
print(f"Read image with shape: {im.shape}, dtype: {im.dtype}")

# Modify the image (e.g., convert to grayscale)
grayscale_im = np.dot(im[...,:3], [0.2989, 0.5870, 0.1140]).astype(np.uint8)
print(f"Grayscale image shape: {grayscale_im.shape}, dtype: {grayscale_im.dtype}")

# Write the modified image to a file
iio.imwrite('chelsea_grayscale.png', grayscale_im)
print("Saved 'chelsea_grayscale.png'")

# Clean up the created file (optional)
import os
# os.remove('chelsea_grayscale.png')

view raw JSON →