ffmpeg

library1.4pypypi✓ verified 90d ago

The `ffmpeg` Python package (often referred to as `ffmpeg-python`) provides a lightweight, fluent Python wrapper for the `ffmpeg` command-line tool. It enables programmatic construction of `ffmpeg` commands, management of audio/video streams, application of filters, and format conversions. It currently stands at version 1.4, with its release cadence tied to upstream `ffmpeg` tool features and community contributions.

data serialization devops

pip install ffmpeg

github ↗package ↗

INSTALL

IMPORT

SIG · FFMPEG

ffmpeg

datapythonv1.4

Install

2.4s avg

Import

—

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4 · 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.920 runs

installs and imports cleanly · install 0.0s · import 0.000s · 19.2MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 2.4s · import 0.000s · 20MB

17MB installed

● package 17MB

Code

Verified usage

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

ffmpeg

✓ import ffmpeg

This quickstart demonstrates how to construct and compile an `ffmpeg` command using the Python wrapper. To execute the command (e.g., `ffmpeg.run()`), the `ffmpeg` command-line tool must be installed separately on your system, and input files like `input.mp4` must exist.

import ffmpeg import os # This quickstart demonstrates compiling an ffmpeg command. # To actually run it, you would need 'input.mp4' to exist # and the ffmpeg CLI tool to be installed and in your PATH. # For full execution, replace 'input.mp4' with an actual file # and remove the '.compile()' to use '.run()'. # Example: Generate an ffmpeg command to re-encode a video # without actually running it, useful for inspection. command_list = ( ffmpeg.input('input.mp4') .output('output_resized.mp4', vf='scale=1280:-1') .compile() ) print(f"Generated ffmpeg command: {' '.join(command_list)}") # Example: Probe a (potentially non-existent) file to get its metadata # For this to run successfully, 'input.mp4' would need to exist # and the ffmpeg CLI tool must be installed. # try: # probe_info = ffmpeg.probe('input.mp4') # print("Probe information:") # print(probe_info) # except ffmpeg.Error as e: # print(f"Error probing file: {e.stderr.decode()}")

Debug

Known issues

gotchaThe Python `ffmpeg` package is merely a wrapper. The actual `ffmpeg` command-line executable must be installed separately on your system (e.g., via `apt`, `brew`, `choco`, or by downloading binaries) and be available in your system's PATH for the Python library to function.

fix

Install the `ffmpeg` CLI tool. On macOS: `brew install ffmpeg`. On Debian/Ubuntu: `sudo apt update && sudo apt install ffmpeg`. On Windows, download from `ffmpeg.org` and add to PATH.

affects: All versions

gotchaOperations involving the `ffmpeg` CLI tool can fail for various reasons (e.g., invalid input, missing codecs, file permissions). Always wrap `ffmpeg.run()` calls in a `try-except` block to catch `ffmpeg.Error` and inspect `e.stderr` for detailed diagnostic information.

fix

Use `try: ffmpeg.run(...) except ffmpeg.Error as e: print(f"Error: {e.stderr.decode()}")` to handle errors gracefully and get feedback from the underlying process.

affects: All versions

gotchaBy default, `ffmpeg` processes files on disk. For handling raw byte data in memory (e.g., from NumPy arrays, OpenCV), you must explicitly use `pipe_input=True` and/or `pipe_output=True` in your input/output nodes, and pass `capture_stdout=True`, `capture_stderr=True` (or `stdout=subprocess.PIPE` directly) to `ffmpeg.run()` to manage data streams.

fix

For input from memory: `ffmpeg.input('pipe:', format='rawvideo', ... , pix_fmt='rgb24', s='640x480', pipe_input=True)`. For output to memory: `.output('pipe:', format='rawvideo', ... , pipe_output=True).run(capture_stdout=True)`.

affects: All versions

gotchaThe `ffmpeg.run()` function is blocking, meaning your Python script will pause until the `ffmpeg` process completes. For long-running video processing tasks in applications that need to remain responsive, consider executing `ffmpeg.run_async()` for non-blocking execution or offloading the operation to a separate thread or background process.

fix

Use `process = ffmpeg.run_async(...)` to get a `subprocess.Popen` object, then manage it (e.g., `process.wait()`, `process.poll()`) or integrate with `asyncio`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ffmpeg'

The Python package `ffmpeg-python` is not installed in the active Python environment, or an incorrect package like `python-ffmpeg` was installed instead.

fix

Ensure `ffmpeg-python` is installed using `pip install ffmpeg-python` or `conda install -c conda-forge ffmpeg-python`.

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

The underlying `ffmpeg` command-line tool (the binary executable) is not installed on the system, or its executable path is not included in the system's PATH environment variable, which `ffmpeg-python` needs to locate it.

fix

Install the `ffmpeg` command-line tool for your operating system (e.g., via Homebrew on macOS, apt-get on Linux, or by downloading binaries and adding to PATH on Windows).

AttributeError: module 'ffmpeg' has no attribute 'input'

This usually happens when there is a Python file named `ffmpeg.py` in your project directory, which shadows the actual `ffmpeg-python` library, preventing it from being imported correctly, or an incompatible `ffmpeg` Python package was installed.

fix

Rename any local file named `ffmpeg.py` to something else (e.g., `my_ffmpeg_script.py`) to avoid conflicts, and ensure `ffmpeg-python` is installed and correctly imported.

BrokenPipeError: [Errno 32] Broken pipe

This error occurs when the `ffmpeg` subprocess terminates unexpectedly, often due to invalid arguments passed to `ffmpeg`, issues with input/output streams, or if a process writing to `ffmpeg`'s stdin closes prematurely.

fix

Carefully review the `ffmpeg-python` command arguments to ensure they are valid for the `ffmpeg` binary, check for proper handling of input/output pipes, and ensure that the `ffmpeg` process completes successfully with the given parameters.

Unable to find a suitable output format for

The `ffmpeg` command-line tool, invoked by `ffmpeg-python`, cannot determine a suitable output format or codec based on the provided arguments and the output file extension, or the arguments themselves are incorrectly specified.

fix

Verify that the output file extension is appropriate for the desired format and codec, and ensure all codec and format-related arguments (e.g., `vcodec`, `acodec`, `f`) are correct and compatible with the `ffmpeg` tool version being used.

Upgrade

Version history

1.4latest on PyPI · released Oct 8, 2018

Audit

Dependencies

No dependency data recorded yet.

Agent activity

47 hits · last 30 days

node

Resources

githubhttps://github.com/jiashaokun/ffmpeg ↗

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