Skip to content
Python library for reading and writing image data
Python PowerShell
Branch: master
Clone or download
kmilos and almarklein Fix for handling TIFF predictor value of 1 (NONE) (#499)
* Expose TIFF predictor tag for reading and writing

* Handle special case of TIFF predictor value of 1 (NONE)

* Revert "Merge from upstream"

This reverts commit 323b0e8, reversing
changes made to 8a9bcd0.
Latest commit 09c34cc Jan 13, 2020


PyPI Version Supported Python Versions Build Status Coverage Status Documentation Status PyPi Download stats DOI


Imageio is a Python library that provides an easy interface to read and write a wide range of image data, including animated images, video, volumetric data, and scientific formats. It is cross-platform, runs on Python 3.5+, and is easy to install.


Here's a minimal example of how to use imageio. See the docs for more examples.
import imageio
im = imageio.imread('imageio:chelsea.png')  # read a standard image
im.shape  # im is a numpy array
>> (300, 451, 3)
imageio.imwrite('~/chelsea-gray.jpg', im[:, :, 0])

API in a nutshell

As a user, you just have to remember a handfull of functions:
  • imread() and imwrite() - for single images
  • mimread() and mimwrite() - for image series (animations)
  • volread() and volwrite() - for volumetric image data
  • get_reader() and get_writer() - for more control (e.g. streaming or compression)
  • See the user api for more information


  • Simple interface via a consise set of functions.
  • Easy to install using conda or pip.
  • Few dependencies (only Numpy and Pillow).
  • Pure Python, runs on Python 3.5+, and Pypy
  • Cross platform, runs on Windows, Linux, OS X (Raspberry Pi planned)
  • Lots of supported formats.
  • Can read from file names, file objects, zipfiles, http/ftp, and raw bytes.
  • Easy to extend using plugins.
  • Code quality is maintained with many tests and continuous integration.

Citing imageio

If you use imageio for scientific work, we would appreciate a citation. We have a DOI!


Imageio has a relatively simple core that provides a common interface to different file formats. This core takes care of reading from different sources (like http), and exposes a simple API for the plugins to access the raw data. All file formats are implemented in plugins. Additional plugins can easily be registered.

Some plugins rely on external libraries (e.g. ffmpeg). Imageio provides a way to download these with one function call, and prompts the user to do so when needed. The download is cached in your appdata directory, this keeps imageio light and scalable.

Imageio provides a wide range of image formats, including scientific formats. Any help with implementing more formats is very welcome!

The codebase adheres to (a subset of) the PEP8 style guides. We strive for maximum test coverage (100% for the core, >95% for each plugin).


Minimal requirements:

  • Python 3.5+
  • Numpy
  • Pillow

Optional Python packages:

  • imageio-ffmpeg (for working with video files)
  • itk or SimpleITK (for ITK formats)
  • astropy (for FITS plugin)
  • osgeo (for GDAL plugin)

Still on an earlier version of Python? Imageio version 2.6.x supports Python 2.7 and 3.4.

Origin and outlook

Imageio was based out of the frustration that many libraries that needed to read or write image data produced their own functionality for IO. PIL did not meet the needs very well, and libraries like scikit-image need to be able to deal with scientific formats. There was a need for a good image io library, which is an easy dependency, easy to maintain, and scalable to exotic file formats.

Imageio started out as component of the scikit-image project, through which it was able to support a lot of common formats. We created a simple but powerful core, a clean user API, and a proper plugin system.

The purpose of imageio is to support reading and writing of image data. We're not processing images, you should use e.g. scikit-image for that. Imageio should be easy to install and be lightweight. Imageio's plugin system makes it possible to scale the number of supported formats and still keep a small footprint.

It is our hope to form a group of developers, whom each maintain one or more plugins. In that way, the burden of each developer is low, and together we can make imageio into a really useful library!


Install a complete development environment:

pip install -r requirements.txt
pip install -e .

N.B. this does not include GDAL because it has awkward compiled dependencies

You may see failing test(s) due to missing installed components. On ubuntu, do sudo apt install libfreeimage3

Style checks, unit tests and coverage are controlled by invoke. Before committing, check these with:

# reformat code on python 3.6+
invoke autoformat
# check there are no style errors
invoke test --style
# check the tests pass
invoke test --unit
# check test coverage (re-runs tests)
invoke test --cover
You can’t perform that action at this time.