---
id: imageio-ffmpeg
version: "0.6.0"
license: BSD-2-Clause
license_treatment: permissive
maintenance: dormant
---

# imageio-ffmpeg — FFMPEG wrapper for Python

License: permissive · Maintenance: dormant · Downloads: 14.3M/mo

## What it is and what it does

imageio-ffmpeg is a lightweight Python wrapper that spawns ffmpeg as a subprocess and communicates video frames over pipes using Python generators. It bundles platform-specific ffmpeg binaries in wheels for Windows, macOS (Intel and ARM), and Linux, eliminating the need to install ffmpeg separately on common platforms. The library provides two main functions: read_frames() to iterate over video frames with metadata, and write_frames() to encode frames into a video file. It has no runtime dependencies and works with Python 3.9+.

The package is designed for straightforward video I/O tasks where you need to read or write frames programmatically. It is lower-level than imageio's ffmpeg plugin but higher-level than calling ffmpeg directly. The documentation notes that PyAV is now a faster, more feature-rich alternative with binary wheels for many platforms, making it worth considering if you need better performance or more advanced ffmpeg features.

Use it for:

- Extract frames from video files for computer vision or machine learning preprocessing pipelines.
- Encode sequences of image frames or numpy arrays into video files with custom codecs and bitrates.
- Build video processing tools that need reliable ffmpeg subprocess management without external system dependencies.
- Integrate video I/O into scientific or educational applications where ffmpeg is needed but system installation is inconvenient.
- Automate video format conversion or re-encoding with fine control over ffmpeg parameters (pixel format, fps, quality, codec).

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a simple Python wrapper around ffmpeg for reading and writing video frames via generators, bundling platform-specific ffmpeg binaries in wheels.

Yes, if you need straightforward video frame reading/writing without managing ffmpeg installation separately. The bundled binaries and zero runtime dependencies make it convenient for cross-platform distribution. However, consider PyAV instead if you need better performance, more advanced features, or are already comfortable with C-level bindings. The dormant maintenance status (575 days since release) is not a blocker for stable use but means security or compatibility updates may lag; monitor the repository for any critical ffmpeg vulnerabilities.

## Install

pip install imageio-ffmpeg
uv add imageio-ffmpeg
poetry add imageio-ffmpeg

## Installing imageio-ffmpeg

Before you install: Medium install friction due to platform-specific wheels (Windows, macOS Intel/ARM, Linux x86_64/aarch64), but wheels include ffmpeg binaries so no external system dependency required. Dormant maintenance (575 days since last release) but repo remains active; last commit 2025-01-16.

License in practice: BSD-2-Clause is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart:

pip install imageio-ffmpeg

from imageio_ffmpeg import read_frames, write_frames

# Read frames
reader = read_frames('video.mp4')
meta = reader.__next__()
for frame in reader:
    process(frame)

# Write frames
writer = write_frames('output.mp4', size=(width, height))
writer.send(None)
for frame in frames:
    writer.send(frame)
writer.close()

Requires Python 3.9 or later. Wheels are platform-specific; installation on unsupported architectures or older Linux kernels (pre-2.6.32) may require building from source or providing your own ffmpeg binary via IMAGEIO_FFMPEG_EXE environment variable.

Verify before relying:

- Whether the included ffmpeg binary is kept current with upstream ffmpeg security patches and feature releases.
- Performance characteristics compared to PyAV or direct ffmpeg subprocess calls for typical video workloads.
- Compatibility with ffmpeg versions older than those bundled in the wheels.

## Package facts

- License: BSD-2-Clause (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: dormant
- Downloads: 14.3M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ffmpeg python wrapper, read write video frames, video processing python, ffmpeg binaries wheels, video file manipulation, frame extraction encoding, subprocess ffmpeg interface, video-io, ffmpeg-wrapper, cross-platform

[View on SkillFed](https://skillfed.io/packages/imageio-ffmpeg) · [View on PyPI](https://pypi.org/project/imageio-ffmpeg/)