API Reference#

ImageIO’s API follows the usual idea of choosing sensible defaults for the average user, but giving you fine grained control where you need it. As such the API is split into two parts: The Core API, which covers standard use-cases, and a plugin/backend specific API, which allows you to take full advantage of a backend and its unique features.

Core APIs#

The core API is ImageIOs public frontend. It provides convenient (and powerful) access to the growing number of individual plugins on top of which ImageIO is built. Currently the following APIs exist:

Core API v3


To use this API import it using:

import imageio.v3 as iio


Check the narrative documentation to build intuition for how to use this API. You can find them here: narrative v3 API docs.

imageio.v3.imread(uri, *[, index, plugin, ...])

Read an ndimage from a URI.

imageio.v3.imiter(uri, *[, plugin, ...])

Read a sequence of ndimages from a URI.

imageio.v3.improps(uri, *[, index, plugin, ...])

Read standardized metadata.

imageio.v3.immeta(uri, *[, index, plugin, ...])

Read format-specific metadata.

imageio.v3.imwrite(uri, image, *[, plugin, ...])

Write an ndimage to the given URI.

imageio.v3.imopen(uri, io_mode, *[, plugin, ...])

Open an ImageResource.

Core API v2


This API exists for backwards compatibility. It is a wrapper around calls to the v3 API and new code should use the v3 API directly.


To use this API import it using:

import imageio.v2 as iio


Check the narrative documentation to build intuition for how to use this API. You can find them here: narrative v2 API docs.

imageio.v2.imread(uri[, format])

Reads an image from the specified file.

imageio.v2.mimread(uri[, format, memtest])

Reads multiple images from the specified file.

imageio.v2.volread(uri[, format])

Reads a volume from the specified file.

imageio.v2.mvolread(uri[, format, memtest])

Reads multiple volumes from the specified file.

imageio.v2.imwrite(uri, im[, format])

Write an image to the specified file.

imageio.v2.mimwrite(uri, ims[, format])

Write multiple images to the specified file.

imageio.v2.volwrite(uri, vol[, format])

Write a volume to the specified file.

imageio.v2.mvolwrite(uri, vols[, format])

Write multiple volumes to the specified file.

imageio.v2.get_reader(uri[, format, mode])

Returns a Reader object which can be used to read data and meta data from the specified file.

imageio.v2.get_writer(uri[, format, mode])

Returns a Writer object which can be used to write data and meta data to the specified file.

Plugins & Backend Libraries#

Sometimes, you need to do more than just “load an image, done”. Sometimes you need to use a very specific feature of a very specific backend. ImageIO allows you to do so by allowing its plugins to extend the core API. Typically this is done in the form of additional keyword arguments (kwarg) or plugin-specific methods. Below you can find a list of available plugins and which arguments they support.


Read/Write BSDF files.


Read DICOM files.


Read TIFF from FEI SEM microscopes.


Read/Write video using FFMPEG


Read FITS files.


Read/Write images using FreeImage.


Read GDAL files.


Read LFR files (Lytro Illum).


Read/Write NPZ files.


Read/Write images using OpenCV.


Read/Write images using Pillow/PIL.


Read/Write images using pillow/PIL (legacy).


Read/Write Videos (and images) using PyAV.


Read/Write images using SimpleITK.


Read SPE files.


Read/Write SWF files.


Read/Write TIFF files.


Read/Write TIFF files using tifffile.