Imageio

2.37.3 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install imageio

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg' ↓

cause Imageio relies on the FFmpeg executable for video processing, and this error occurs when the 'ffmpeg' binary is not found in the system's PATH or if the `imageio-ffmpeg` package is not correctly installed to provide it.

fix

Install the imageio-ffmpeg package which bundles the FFmpeg executable: pip install imageio-ffmpeg or ensure FFmpeg is manually installed and its directory is added to your system's PATH.

error AttributeError: module 'imageio' has no attribute 'imread' ↓

cause This error typically arises due to changes in the Imageio API across different versions. Older versions used `imageio.imread()`, then `imageio.v2.imread()` was introduced, and newer versions often revert to `imageio.imread()` with explicit plugin usage or auto-detection.

fix

For Imageio versions 2.9 and newer, try using im = imageio.v2.imread('image.png') or im = imageio.imread('image.png') if using the latest versions that have harmonized the API. Ensure your imageio library is up-to-date with pip install --upgrade imageio.

error AttributeError: module 'imageio.plugins' has no attribute 'ffmpeg' ↓

cause This error occurs when attempting to access the `ffmpeg` plugin directly via `imageio.plugins.ffmpeg` which was a common pattern in older versions of Imageio (e.g., for downloading FFmpeg). The plugin structure or the recommended way to interact with FFmpeg has changed, with `imageio-ffmpeg` now being the primary mechanism.

fix

Instead of directly accessing imageio.plugins.ffmpeg, ensure you have imageio-ffmpeg installed (pip install imageio-ffmpeg) for video capabilities. If you need to specify a format for reading/writing, use imageio.imread('video.mp4', plugin='ffmpeg') or imageio.get_reader('video.mp4', plugin='ffmpeg') and similar for writing. For downloading, the imageio-ffmpeg package handles the binary distribution automatically.

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.38s 111.0M

3.10 alpine (musl) - - 0.35s 111.0M

3.10 slim (glibc) wheel 4.4s 0.33s 108M

3.10 slim (glibc) - - 0.32s 108M

3.11 alpine (musl) wheel - 0.52s 119.6M

3.11 alpine (musl) - - 0.53s 119.6M

3.11 slim (glibc) wheel 4.1s 0.49s 116M

3.11 slim (glibc) - - 0.43s 116M

3.12 alpine (musl) wheel - 0.46s 107.8M

3.12 alpine (musl) - - 0.43s 107.8M

3.12 slim (glibc) wheel 4.0s 0.47s 104M

3.12 slim (glibc) - - 0.45s 104M

3.13 alpine (musl) wheel - 0.37s 107.3M

3.13 alpine (musl) - - 0.41s 107.2M

3.13 slim (glibc) wheel 4.0s 0.44s 103M

3.13 slim (glibc) - - 0.42s 103M

3.9 alpine (musl) wheel - 0.28s 116.7M

3.9 alpine (musl) - - 0.29s 116.7M

3.9 slim (glibc) wheel 5.1s 0.36s 116M

3.9 slim (glibc) - - 0.27s 116M

Imports

iio
wrong
```
import imageio; imageio.imread('file.png')
```
correct
```
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 verified last tested: 2026-04-24

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')