Install & Compatibility
Where this runs
tested against v0.2.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.068s · 21.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.062s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ffmpeg
✓ pip install ffmpeg-python
✗ pip install ffmpeg
Installing 'ffmpeg' or 'python-ffmpeg' from PyPI will install a different, unrelated library. Ensure you install 'ffmpeg-python' for these bindings and use 'import ffmpeg' in your code.
This quickstart demonstrates how to convert a video file from one format (e.g., MP4) to another (e.g., AVI) using `ffmpeg-python`. It creates a stream from an input file, specifies an output file, and then executes the FFmpeg command. For this example to function correctly, an `input.mp4` file must exist, and the FFmpeg binary must be installed and accessible on your system.
import ffmpeg
import os
# Create dummy input file for demonstration
# In a real scenario, 'input.mp4' would be an existing video file.
# For a runnable example without actual FFmpeg, this part would be mocked or use a very small, pre-existing file.
# For this example, we assume 'input.mp4' exists.
# To make it runnable for demonstration, let's create a placeholder.
# WARNING: This part is for demonstration. FFmpeg needs a valid input file.
# In a production environment, ensure 'input.mp4' is a real video file.
input_filename = 'input.mp4'
output_filename = 'output.avi'
# This block is a placeholder to ensure the file exists for a 'runnable' check,
# but FFmpeg still requires a proper media file.
if not os.path.exists(input_filename):
print(f"Please create a dummy video file named '{input_filename}' for this example to fully run with FFmpeg.")
print("Example will proceed by trying to convert, but might fail if FFmpeg can't find/process the file.")
# Example of how you might generate a minimal dummy file if FFmpeg was installed and functional:
# import subprocess
# try:
# subprocess.run(['ffmpeg', '-f', 'lavfi', '-i', 'testsrc=duration=1:size=128x72:rate=10', input_filename], check=True)
# except FileNotFoundError:
# print("FFmpeg command-line tool not found. Please install FFmpeg.")
# except subprocess.CalledProcessError as e:
# print(f"Error creating dummy input file: {e}")
try:
stream = ffmpeg.input(input_filename)
stream = ffmpeg.output(stream, output_filename)
ffmpeg.run(stream, overwrite_output=True)
print(f"Successfully converted {input_filename} to {output_filename}")
except ffmpeg.Error as e:
print(f"FFmpeg error: {e.stderr.decode('utf8')}")
except FileNotFoundError:
print("FFmpeg command not found. Please ensure FFmpeg is installed and in your system's PATH.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaThe `ffmpeg-python` library is a wrapper for the external FFmpeg binary. You *must* install FFmpeg separately on your system and ensure its executables are available in your system's PATH environment variable for `ffmpeg-python` to work. `ffmpeg-python` does not install FFmpeg for you.fixInstall FFmpeg for your operating system (e.g., `sudo apt install ffmpeg` on Debian/Ubuntu, `brew install ffmpeg` on macOS, or download from the official FFmpeg website for Windows and add to PATH).
affects: All versions
gotchaSome FFmpeg filters inherently drop audio or video streams if not explicitly handled. If you encounter missing audio or video in your output, you may need to explicitly select and re-combine streams using `.audio` and `.video` operators.fixUse `stream.audio` and `stream.video` to reference and process audio/video portions separately, then use `ffmpeg.concat()` or similar to re-combine them if needed. Refer to FFmpeg's official documentation for specific filter behaviors.
affects: All versions (intrinsic FFmpeg behavior)
gotchaAbruptly terminating the underlying FFmpeg process (e.g., by killing the Python process) can lead to corrupted output files.fixImplement graceful termination by sending a signal to the FFmpeg process (e.g., `process.terminate()`) and allowing a short sleep period for FFmpeg to finalize the output file. Avoid `taskkill` or similar abrupt methods.
affects: All versions
gotchaWhile `ffmpeg-python` (version 0.2.0) has not been updated since 2019, it remains widely used and functional because it acts as a thin wrapper around the underlying FFmpeg command-line tool. The core FFmpeg binary itself is actively maintained and frequently updated (e.g., FFmpeg 8.1 released March 2026). The stability of your media processing largely depends on keeping your *FFmpeg binary* up-to-date, not necessarily the `ffmpeg-python` wrapper.fixRegularly update your system's FFmpeg binary to benefit from the latest features, bug fixes, and security patches. Check the FFmpeg project's official news for new releases. This library's lack of recent updates does not imply it is broken or incompatible with newer FFmpeg binaries, though very recent, significant breaking changes in FFmpeg's CLI syntax *could* potentially affect it.
affects: All versions
gotchaSome media players or platforms require specific pixel formats (e.g., `yuv420p`) for maximum compatibility. Omitting this can lead to playback issues.fixWhen encoding video, consider adding the `-pix_fmt yuv420p` option to your FFmpeg command via `ffmpeg-python`. Example: `ffmpeg.output(stream, output_filename, pix_fmt='yuv420p').run()`.
affects: All versions (depends on target playback environment)
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg'
The underlying FFmpeg binary (and/or ffprobe) is not installed on the system, or its executable path is not included in the system's PATH environment variable, preventing `ffmpeg-python` from locating it.
fixInstall FFmpeg on your operating system (e.g., `sudo apt install ffmpeg` on Ubuntu, `brew install ffmpeg` on macOS, or download binaries and add to PATH on Windows), and ensure the FFmpeg executable is discoverable via the system's PATH.
RuntimeError: Program 'ffmpeg' is not found; perhaps install ffmpeg using 'apt-get install ffmpeg'.
The `ffmpeg-python` library cannot find the `ffmpeg` executable because it is either not installed on the system or not accessible via the system's PATH environment variable.
fixInstall the FFmpeg command-line tool on your system. For Linux (Debian/Ubuntu), use `sudo apt install ffmpeg`; for macOS, use `brew install ffmpeg`; for Windows, download the binaries from the official FFmpeg website and add the `/bin` directory to your system's PATH.
pip install ffmpeg (instead of pip install ffmpeg-python)
Users often mistakenly install a different, unrelated `ffmpeg` Python package from PyPI, which does not provide the `ffmpeg-python` wrapper functionality.
fixUninstall the incorrect package using `pip uninstall ffmpeg` (and `pip uninstall python-ffmpeg` if installed) and then install the correct wrapper with `pip install ffmpeg-python`.
Output file #0 does not contain any stream
FFmpeg reports this error when it fails to find any valid audio or video streams in the input or through the processing pipeline that it can write to the output file, often due to incorrect input paths, missing streams, or faulty command syntax.
fixVerify that your input file exists and contains valid streams (use `ffprobe -show_streams your_file.mp4`). Ensure your `ffmpeg-python` command correctly maps input streams to the output using `.input()` and `.output()`, and that any filters or operations don't inadvertently drop all streams without replacing them. For example, explicitly mapping streams like `.output(output_file, map='0:v', map='0:a')` can help.
Error opening filters!
This FFmpeg error indicates a problem with the filtergraph specified in the command, often due to incorrect syntax for a filter, an unsupported filter, or invalid arguments passed to a filter.
fixCarefully review the filter arguments and syntax in your `ffmpeg-python` chain. Ensure all filter names are correct and that their parameters conform to FFmpeg's expectations (e.g., correct data types, valid ranges, proper escaping of special characters in paths). Test complex filter graphs directly with the `ffmpeg` command-line tool to debug the filter string before integrating it into `ffmpeg-python`.
Upgrade
Version history
0.2.0latest on PyPI · released Jul 6, 2019
Audit
Dependencies
FFmpegrequiredffmpeg-python is a wrapper around the FFmpeg command-line utility. The FFmpeg binary must be installed separately on your system and accessible via the system's PATH environment variable for ffmpeg-python to function.