{"id":643,"library":"imageio","title":"Imageio","description":"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.","status":"active","version":"2.37.3","language":"python","source_language":"en","source_url":"https://github.com/imageio/imageio","tags":["image processing","video processing","scientific data","io","multimedia","computer vision"],"install":[{"cmd":"pip install imageio","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Core dependency for image data representation.","package":"NumPy","optional":false},{"reason":"Core dependency for common image formats (JPG, PNG, GIF, TIFF).","package":"Pillow>=8.3.2","optional":false},{"reason":"Optional plugin for robust video file (MP4, AVI, etc.) reading and writing, bundles FFmpeg binaries. Recommended over PyAV for simpler setup.","package":"imageio-ffmpeg","optional":true},{"reason":"Optional plugin for video file reading and writing. Offers C-level wrapping for performance but may require more complex installation than imageio-ffmpeg.","package":"pyav","optional":true},{"reason":"Optional plugin for advanced TIFF file support, particularly for scientific and volumetric data.","package":"tifffile","optional":true},{"reason":"Optional plugin for ITK (Insight Segmentation and Registration Toolkit) data formats.","package":"itk","optional":true},{"reason":"Optional plugin for SimpleITK data formats (alternative to ITK).","package":"SimpleITK","optional":true},{"reason":"Optional plugin for FITS (Flexible Image Transport System) format support, common in astronomy.","package":"astropy","optional":true},{"reason":"Optional plugin for FLIF (Free Lossless Image Format) image files.","package":"imageio-flif","optional":true}],"imports":[{"note":"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.","wrong":"import imageio; imageio.imread('file.png')","symbol":"iio","correct":"import imageio.v3 as iio"}],"quickstart":{"code":"import imageio.v3 as iio\nimport numpy as np\n\n# Read a standard image from imageio's sample data\nim = iio.imread('imageio:chelsea.png')\nprint(f\"Read image with shape: {im.shape}, dtype: {im.dtype}\")\n\n# Modify the image (e.g., convert to grayscale)\ngrayscale_im = np.dot(im[...,:3], [0.2989, 0.5870, 0.1140]).astype(np.uint8)\nprint(f\"Grayscale image shape: {grayscale_im.shape}, dtype: {grayscale_im.dtype}\")\n\n# Write the modified image to a file\niio.imwrite('chelsea_grayscale.png', grayscale_im)\nprint(\"Saved 'chelsea_grayscale.png'\")\n\n# Clean up the created file (optional)\nimport os\n# os.remove('chelsea_grayscale.png')\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=2.9.0 (with deprecation warnings), >=2.30.0 (v3 as default)"},{"fix":"Install the necessary video backend: `pip install imageio-ffmpeg` (recommended for most users as it bundles FFmpeg) or `pip install pyav`.","message":"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`).","severity":"gotcha","affected_versions":"All versions supporting video I/O"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T17:08:18.227Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'"},{"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`.","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.","error":"AttributeError: module 'imageio' has no attribute 'imread'"},{"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.","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.","error":"AttributeError: module 'imageio.plugins' has no attribute 'ffmpeg'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"2.37.3","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.38,"mem_mb":10.8,"disk_size":"111.0M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.35,"mem_mb":10.8,"disk_size":"111.0M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.4,"import_time_s":0.33,"mem_mb":10.7,"disk_size":"108M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.32,"mem_mb":10.7,"disk_size":"108M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.52,"mem_mb":11.5,"disk_size":"119.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.53,"mem_mb":11.5,"disk_size":"119.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4.1,"import_time_s":0.49,"mem_mb":11.5,"disk_size":"116M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":11.5,"disk_size":"116M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":11.3,"disk_size":"107.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":11.3,"disk_size":"107.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":0.47,"mem_mb":11.3,"disk_size":"104M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.45,"mem_mb":11.3,"disk_size":"104M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.37,"mem_mb":11.2,"disk_size":"107.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":11.2,"disk_size":"107.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":4,"import_time_s":0.44,"mem_mb":11.2,"disk_size":"103M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.42,"mem_mb":11.2,"disk_size":"103M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.28,"mem_mb":10.4,"disk_size":"116.7M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.29,"mem_mb":10.4,"disk_size":"116.7M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":5.1,"import_time_s":0.36,"mem_mb":10.4,"disk_size":"116M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.27,"mem_mb":10.4,"disk_size":"116M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}