python-ffmpeg

2.0.12 verified Mon Apr 27 auth: no python

A Python binding for FFmpeg that provides both synchronous and asynchronous APIs to transcode, process, and stream media files. Current version is 2.0.12, with active development and regular releases.

pip install python-ffmpeg

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg' ↓

cause FFmpeg executable not installed or not in PATH.

fix

Install FFmpeg (e.g., 'sudo apt install ffmpeg' or 'brew install ffmpeg') and ensure it's in PATH.

error TypeError: cannot be used with 'await' ↓

cause Calling an async method without await, or calling a coroutine as if it were a sync function.

fix

Use 'await ffmpeg.execute()' inside an async function.

Warnings

breaking Version 2.0 completely rewrote the API from v1.x. The old `ffmpeg-python`-style FFmpeg() is replaced with the new async-first API. ↓

fix Migrate to new async/sync API. See migration guide in repo.

breaking Async methods must be awaited; calling execute() without await returns a coroutine object instead of running. ↓

fix Use 'await ffmpeg.execute()' inside an async function.

gotcha Progress callbacks require the 'Progress' class from ffmpeg.progress module, not from ffmpeg itself. ↓

fix Use: from ffmpeg.progress import Progress

gotcha FFmpeg binary must be installed separately and accessible via PATH, otherwise the library will raise a subprocess error. ↓

fix Install FFmpeg (e.g., 'sudo apt install ffmpeg' or download from ffmpeg.org).

Imports

FFmpeg
```
from ffmpeg import FFmpeg
```
Direct import of the main class.

Progress

wrong

from ffmpeg import Progress

correct

from ffmpeg.progress import Progress

Progress is in the submodule ffmpeg.progress.

Quickstart

Basic async usage: transcode an MP4 file.

import asyncio
from ffmpeg import FFmpeg

async def main():
    ffmpeg = FFmpeg()
    ffmpeg.input('input.mp4')
    ffmpeg.output('output.mp4')
    await ffmpeg.execute()

asyncio.run(main())