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.
Install & Compatibility
Where this runs
tested against v2.37.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.405s · 111MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 4.4s · import 0.405s · 108MB
111MB installed
● package 111MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
iio
✓ import imageio.v3 as iio
✗ import imageio; imageio.imread('file.png')
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.
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')
Debug
Known issues
breakingThe 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.fixMigrate 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.
affects: >=2.9.0 (with deprecation warnings), >=2.30.0 (v3 as default)
gotchaFor 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`).fixInstall the necessary video backend: `pip install imageio-ffmpeg` (recommended for most users as it bundles FFmpeg) or `pip install pyav`.
affects: All versions supporting video I/O
gotchaWhile 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.fixEnsure 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.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'
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.
fixInstall 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.
AttributeError: module 'imageio' has no attribute 'imread'
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.
fixFor 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`. AttributeError: module 'imageio.plugins' has no attribute 'ffmpeg'
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.
fixInstead 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. Audit
Dependencies
NumPyrequiredCore dependency for image data representation.
Pillow>=8.3.2requiredCore dependency for common image formats (JPG, PNG, GIF, TIFF).
imageio-ffmpegoptionalOptional plugin for robust video file (MP4, AVI, etc.) reading and writing, bundles FFmpeg binaries. Recommended over PyAV for simpler setup.
pyavoptionalOptional plugin for video file reading and writing. Offers C-level wrapping for performance but may require more complex installation than imageio-ffmpeg.
tifffileoptionalOptional plugin for advanced TIFF file support, particularly for scientific and volumetric data.
itkoptionalOptional plugin for ITK (Insight Segmentation and Registration Toolkit) data formats.
SimpleITKoptionalOptional plugin for SimpleITK data formats (alternative to ITK).
astropyoptionalOptional plugin for FITS (Flexible Image Transport System) format support, common in astronomy.
imageio-flifoptionalOptional plugin for FLIF (Free Lossless Image Format) image files.