Registry / data / imageio-ffmpeg

imageio-ffmpeg

library0.6.0pypypi✓ verified 25d ago

imageio-ffmpeg is a Python library that provides a convenient wrapper around the FFMPEG executable, enabling Python applications to easily read and write video files. It bundles pre-compiled FFMPEG binaries for various platforms, simplifying deployment. The current version is 0.6.0, and it generally follows a release cadence tied to bug fixes, dependency updates, and new platform support.

data serialization

pip install imageio-ffmpeg

github ↗package ↗

INSTALL

IMPORT

SIG · IMAGEIO-FFMPEG

imageio-ffmpeg

datapythonv0.6.0

Install

2.2s avg

Import

83ms

Disk

54MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.6.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.086s · 19.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.080s · 95MB

54MB installed

● package 54MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

imageio_ffmpeg

✓ import imageio_ffmpeg as iio_ffmpeg

This quickstart demonstrates how to use `imageio-ffmpeg` to write a simple video file (e.g., an MP4 with a moving red square). It initializes a video writer, generates a series of NumPy arrays representing frames, and sends them to the FFMPEG process. It also shows how to check the FFMPEG executable path being used.

import imageio_ffmpeg as iio_ffmpeg import numpy as np # Define video parameters filename = 'my_video_output.mp4' width, height = 640, 480 fps = 30 num_frames = 100 print(f"Using FFMPEG executable: {iio_ffmpeg.get_ffmpeg_exe()}") try: # Initialize the writer writer = iio_ffmpeg.write_frames(filename, (width, height), fps=fps) writer.send(None) # Start the pipe for i in range(num_frames): # Create a simple frame: black background with a moving red square frame = np.zeros((height, width, 3), dtype=np.uint8) x_offset = (i * 5) % (width - 100) # Move square across width frame[50:150, x_offset : x_offset + 100] = [255, 0, 0] # Red square writer.send(frame) writer.close() print(f"Video saved to {filename}") except Exception as e: print(f"An error occurred: {e}") print("Ensure FFMPEG is correctly configured or its bundled binary is accessible.")

Debug

Known issues

breakingStarting from version 0.5.0, imageio-ffmpeg requires Python 3.9 or newer. Users on older Python versions (e.g., Python 3.8 or earlier) will encounter installation failures or runtime errors.

fix

Upgrade your Python environment to 3.9 or a later version.

affects: >=0.5.0

gotchaAlthough imageio-ffmpeg bundles pre-compiled FFMPEG binaries, sometimes these might not be compatible with specific system configurations or users may prefer to use a system-wide or custom FFMPEG installation. If you encounter issues like 'ffmpeg not found' or unexpected encoding failures, verify the FFMPEG executable path.

fix

You can explicitly set the FFMPEG executable path using `imageio_ffmpeg.set_ffmpeg_exe('/path/to/your/ffmpeg')` or ensure that `ffmpeg` is available in your system's PATH. The path used can be checked with `imageio_ffmpeg.get_ffmpeg_exe()`.

affects: All

gotchaimageio-ffmpeg can be used as a standalone wrapper for FFMPEG, but it's primarily designed to be a backend for the `imageio` library for video I/O. Users sometimes confuse when to import `imageio` vs. `imageio_ffmpeg`. For higher-level, more abstract video operations integrated with image processing, `imageio` is often sufficient. For direct, lower-level control over FFMPEG parameters, `imageio_ffmpeg` is the correct choice.

fix

Understand your use-case: use `imageio` for general image/video I/O if `imageio-ffmpeg` is configured as its backend, or directly use `imageio_ffmpeg` when you need explicit control over FFMPEG processes and arguments.

affects: All

deprecatedIn version 0.5.0, imageio-ffmpeg migrated from using `pkg_resources` to `importlib.resources` for internal resource management. While this generally doesn't affect standard API usage, any advanced users who relied on direct interaction with `imageio-ffmpeg`'s internal resource loading mechanisms via `pkg_resources` might experience breaking changes.

fix

Review any custom code that interacts with internal resource paths or loaders; adapt it to use `importlib.resources` patterns if necessary. For most users, no action is required.

affects: >=0.5.0

breakingThe script failed because a required dependency, `numpy`, was not found. `imageio-ffmpeg` often relies on `numpy` (either directly or through other libraries like `imageio`) for array manipulation and image processing. This error indicates `numpy` was not installed in the environment.

fix

Install `numpy` using pip: `pip install numpy`. If your application depends on `imageio` which then uses `imageio-ffmpeg` as a backend, ensure both `imageio` and `numpy` are installed.

affects: All

breakingThe library (or its common use-cases) depends on 'numpy'. If you encounter a 'ModuleNotFoundError: No module named 'numpy'', it indicates that this essential dependency is missing.

fix

Ensure 'numpy' is installed in your environment by running `pip install numpy`.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'imageio_ffmpeg'

The `imageio_ffmpeg` package is not installed in the current Python environment, or there's a conflict with `imageio` versions, especially when `imageio` itself was updated to require `imageio_ffmpeg` as a separate dependency.

fix

Ensure `imageio-ffmpeg` is installed: `pip install imageio-ffmpeg` or `pip install --upgrade imageio-ffmpeg` to get the latest compatible version. If using older `moviepy` versions, downgrading `imageio` might also be necessary in some cases (e.g., `pip install imageio==2.4.1`).

RuntimeError: No ffmpeg exe could be found. Install ffmpeg on your system, or set the IMAGEIO_FFMPEG_EXE environment variable.

The `imageio-ffmpeg` library cannot locate the `ffmpeg` executable. This can happen if `imageio-ffmpeg` failed to download its bundled `ffmpeg` binary, if `ffmpeg` is not installed system-wide and added to PATH, or if a custom `ffmpeg` path is not explicitly provided to the library.

fix

First, ensure `imageio-ffmpeg` is installed correctly, as it usually bundles `ffmpeg`. If the error persists, install `ffmpeg` system-wide (e.g., `sudo apt-get install ffmpeg` on Linux, `brew install ffmpeg` on macOS, or download from the official FFmpeg website for Windows and add to PATH). Alternatively, set the `IMAGEIO_FFMPEG_EXE` environment variable to the absolute path of your `ffmpeg` executable: `os.environ["IMAGEIO_FFMPEG_EXE"] = "/path/to/ffmpeg"` in your Python script before using `imageio`.

RuntimeError: imageio.ffmpeg.download() has been deprecated. Use 'pip install imageio-ffmpeg' instead.'

This error occurs when using an outdated method to acquire the FFmpeg executable. In newer versions of `imageio` and `imageio-ffmpeg`, the `ffmpeg` binary is distributed directly with the `imageio-ffmpeg` package, making the separate `download()` function obsolete.

fix

Remove any calls to `imageio.ffmpeg.download()` from your code. Ensure `imageio-ffmpeg` is installed in your environment via pip: `pip install imageio-ffmpeg`. The library will then automatically locate the bundled FFmpeg binary.

OSError: Unable to download 'ffmpeg.win32.exe'. Perhaps there is a no internet connection? If there is, please report this problem.

The `imageio-ffmpeg` library attempted to download a pre-compiled FFmpeg binary but failed due to network connectivity issues, SSL certificate verification failures, or potentially a firewall blocking the download.

fix

Check your internet connection and proxy settings. If SSL errors occur, updating `certifi` (`pip install --upgrade certifi`) or temporarily installing with `--trusted-host` might help. As a workaround, you can manually download the appropriate `ffmpeg` executable for your system from the official FFmpeg website and then set the `IMAGEIO_FFMPEG_EXE` environment variable to its path.

Upgrade

Version history

0.6.0latest on PyPI · released Jan 16, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

23 hits · last 30 days

node

Resources

githubhttps://github.com/imageio/imageio-ffmpeg ↗

packagehttps://pypi.org/project/imageio-ffmpeg/ ↗