Install & Compatibility
Where this runs
tested against v1.0.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.028s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.024s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FFmpeg
✓ from ffmpy import FFmpeg
✗ from ffmpy import FFMPEG
The primary class was renamed from `FFMPEG` to `FFmpeg` in version 1.0.0.
This example demonstrates how to convert a dummy WAV file to MP3 using ffmpy. It includes creating a temporary input file, executing the FFmpeg command, and basic error handling, along with cleanup.
import os
import struct
from ffmpy import FFmpeg, FFExecutableNotFoundError, FFRuntimeError
dummy_input_path = "dummy_input.wav"
dummy_output_path = "dummy_output.mp3"
try:
# Create a dummy 1-second 8kHz mono 8-bit silent WAV file
# RIFF header
chunk_id = b'RIFF'
chunk_size = 36 + 8000 # Header (36) + data (8000 samples * 1 byte/sample)
format_str = b'WAVE'
# FMT sub-chunk
subchunk1_id = b'fmt '
subchunk1_size = 16
audio_format = 1 # PCM
num_channels = 1 # Mono
sample_rate = 8000
byte_rate = sample_rate * num_channels * 1 # 8000 * 1 * 1
block_align = num_channels * 1 # 1 * 1
bits_per_sample = 8
# DATA sub-chunk
subchunk2_id = b'data'
subchunk2_size = 8000 # 1 second of 8-bit 8kHz mono
with open(dummy_input_path, 'wb') as f:
f.write(chunk_id)
f.write(struct.pack('<I', chunk_size))
f.write(format_str)
f.write(subchunk1_id)
f.write(struct.pack('<I', subchunk1_size))
f.write(struct.pack('<H', audio_format))
f.write(struct.pack('<H', num_channels))
f.write(struct.pack('<I', sample_rate))
f.write(struct.pack('<I', byte_rate))
f.write(struct.pack('<H', block_align))
f.write(struct.pack('<H', bits_per_sample))
f.write(subchunk2_id)
f.write(struct.pack('<I', subchunk2_size))
f.write(b'\x80' * subchunk2_size) # 8-bit unsigned silence is 0x80 (128)
ff = FFmpeg(
inputs={dummy_input_path: None},
outputs={dummy_output_path: '-codec:a libmp3lame -q:a 2'}
)
print(f"Executing FFmpeg command: {ff.cmd}")
ff.run()
print(f"Successfully converted '{dummy_input_path}' to '{dummy_output_path}'")
except FFExecutableNotFoundError:
print("Error: FFmpeg executable not found. Please ensure FFmpeg is installed and in your system's PATH.")
except FFRuntimeError as e:
print(f"Error during FFmpeg execution. Exit code: {e.exit_code}")
print(f"FFmpeg stderr: {e.stderr.decode('utf-8')}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
if os.path.exists(dummy_input_path):
os.remove(dummy_input_path)
if os.path.exists(dummy_output_path):
os.remove(dummy_output_path)
print("Cleaned up dummy files.")
Debug
Known issues
gotchaffmpy is a wrapper around the FFmpeg executable, not a pure Python implementation. You must have FFmpeg installed on your system and available in your system's PATH for ffmpy to function.fixInstall FFmpeg on your operating system (e.g., via Homebrew on macOS, apt on Debian/Ubuntu, or downloading binaries).
affects: All versions
breakingVersion 1.0.0 represents a significant rewrite. Key changes include renaming the main class from `FFMPEG` to `FFmpeg`, and substantial modifications to the constructor signature and method interfaces. Code written for 0.x versions will not work with 1.0.0 without adaptation.fixReview the new `FFmpeg` class constructor and method signatures. Update imports and method calls to match the 1.0.0 API.
affects: >=1.0.0 (when migrating from <1.0.0)
gotchaFFmpeg options are typically passed as a single string per input/output file in the `inputs` and `outputs` dictionaries. It does not accept a global list or string of options, which is a common mistake for users familiar with `ffmpeg-python` or complex CLI usage.fixPass FFmpeg options as a string value associated with each input/output file key, e.g., `outputs={'output.mp4': '-c:v libx264 -preset medium'}`. affects: All versions
gotchaffmpy is designed as a 'simple' wrapper. It offers a direct way to run FFmpeg commands but does not aim to expose all of FFmpeg's vast feature set or provide deep programmatic control over every parameter like more complex wrappers (e.g., `ffmpeg-python`).fixAdjust expectations based on the library's scope. For advanced or highly customized FFmpeg operations, consider `ffmpeg-python` or direct subprocess calls.
affects: All versions
Errors
Common errors & fixes
ffmpy.FFExecutableNotFoundError: Executable 'ffmpeg' not found
The `ffmpy` library is a Python wrapper for the FFmpeg command-line tool. This error indicates that the underlying `ffmpeg` executable is either not installed on the system or is not located in the system's PATH environment variable, preventing `ffmpy` from finding and executing it.
fixInstall FFmpeg on your operating system and ensure its executable (`ffmpeg.exe` on Windows, `ffmpeg` on Linux/macOS) is added to your system's PATH. Alternatively, you can explicitly provide the absolute path to the FFmpeg executable when initializing the `FFmpeg` object: `ff = FFmpeg(executable='/path/to/ffmpeg', inputs={'input.mp4': None}, outputs={'output.avi': None})`. FileNotFoundError: [Errno 2] No such file or directory: 'ffprobe'
Similar to the `ffmpeg` executable error, this specific `FileNotFoundError` occurs when `ffmpy` (or a related component attempting to inspect media files) cannot locate the `ffprobe` executable. `ffprobe` is a companion tool to `ffmpeg` used for analyzing media streams.
fixEnsure that `ffprobe` is installed on your system (it usually comes bundled with `ffmpeg`) and that its executable is accessible via the system's PATH. If `ffprobe` is in a custom location, you might need to specify its path explicitly, although `ffmpy` primarily uses `ffmpeg` for transcoding, `ffprobe` might be used internally or by related libraries.
FileNotFoundError: [Errno 2] No such file or directory: 'input.mp4'
This generic `FileNotFoundError` occurs when the input media file (e.g., 'input.mp4' or any other specified file) or the output directory provided to `ffmpy` does not exist at the specified path, or the current user lacks the necessary read/write permissions.
fixVerify that the input file exists at the given path. If specifying an output file, ensure the target directory exists and is writable. It is often safest to use absolute paths for both input and output files to avoid issues related to the current working directory. Also, confirm file permissions allow access.
Upgrade
Version history
1.0.0latest on PyPI · released Nov 11, 2025
Audit
Dependencies
No dependency data recorded yet.