FileNotFoundError
FileNotFoundError: ffmpeg not found on system
Stack trace
FileNotFoundError: ffmpeg not found on system
File "/usr/local/lib/python3.11/site-packages/whisper/audio.py", line 29, in load_audio
ffmpeg_input = subprocess.run(
File "/usr/lib/python3.11/subprocess.py", line 971, in run
raise FileNotFoundError(2, 'No such file or directory', 'ffmpeg')
FileNotFoundError: [Errno 2] No such file or directory: 'ffmpeg' Why it happens
OpenAI Whisper uses FFmpeg as a subprocess to convert audio files (MP3, M4A, OGG, FLAC, WAV, etc.) into raw PCM audio that the model can process. When you call whisper.load_model() and attempt transcription, the library invokes ffmpeg via subprocess.run(). If FFmpeg isn't installed on your system or not added to your system PATH, Python cannot find the executable and raises FileNotFoundError.
Detection
Check if FFmpeg is installed before loading audio: run `which ffmpeg` (macOS/Linux) or `where ffmpeg` (Windows) in your terminal. If no output, FFmpeg is missing. Add a pre-flight check in your code: `subprocess.run(['ffmpeg', '-version'], capture_output=True)` to fail fast with a clear error message.
Causes & fixes
FFmpeg is not installed on your system at all
Install FFmpeg using your package manager: `brew install ffmpeg` (macOS), `choco install ffmpeg` (Windows), or `sudo apt-get install ffmpeg` (Ubuntu/Debian). Verify with `ffmpeg -version`.
FFmpeg is installed but not in your system PATH environment variable
Add FFmpeg's installation directory to PATH. On Windows: Settings > Environment Variables > add C:\ffmpeg\bin to PATH. On macOS/Linux: add export PATH="/usr/local/bin:$PATH" to ~/.bash_profile or ~/.zshrc, then restart your terminal.
Using a virtual environment (venv) without inheriting system FFmpeg
Install FFmpeg system-wide (not in venv: FFmpeg is a system binary, not a Python package). After system install, activate your venv and verify: `which ffmpeg` should resolve to /usr/local/bin/ffmpeg, not a venv path.
Running in Docker/container without FFmpeg in the image
Add `RUN apt-get update && apt-get install -y ffmpeg` to your Dockerfile before installing openai-whisper. For Alpine Linux, use `apk add ffmpeg`.
Code: broken vs fixed
import whisper
import os
# Broken: assumes ffmpeg is in PATH without checking
audio_file = "meeting.mp3"
model = whisper.load_model('large-v3')
result = model.transcribe(audio_file) # ← FileNotFoundError: ffmpeg not found
print(result['text'])import whisper
import os
import subprocess
# Fixed: verify ffmpeg exists before transcribing
def check_ffmpeg():
try:
subprocess.run(['ffmpeg', '-version'], capture_output=True, check=True)
print("✓ FFmpeg found in PATH")
except FileNotFoundError:
raise FileNotFoundError(
"FFmpeg not installed. Install with:\n"
" macOS: brew install ffmpeg\n"
" Ubuntu/Debian: sudo apt-get install ffmpeg\n"
" Windows: choco install ffmpeg\n"
"Then restart your terminal and try again."
)
check_ffmpeg() # ← Check before loading model
audio_file = "meeting.mp3"
model = whisper.load_model('large-v3')
result = model.transcribe(audio_file)
print(result['text'])Workaround
If you cannot install FFmpeg on your system, use the OpenAI Whisper API instead of the local model: `client = OpenAI(api_key=os.environ['OPENAI_API_KEY']); with open(audio_file, 'rb') as f: transcript = client.audio.transcriptions.create(model='whisper-1', file=f); print(transcript.text)`: the API handles all audio decoding server-side.
Prevention
Ensure FFmpeg is installed as part of your project setup documentation and CI/CD pipeline. Add to requirements-system.txt or Dockerfile before installing Python packages. Use environment-specific checks in your startup code to fail with a helpful message, not a mysterious subprocess error. For production deployments, use the OpenAI Whisper API (cloud-hosted) instead of local models to eliminate system dependency issues entirely.