Troubleshooting guide

Fix "ffmpeg not found" in yt-dlp

This error usually means one of two things: ffmpeg is not installed, or it is installed but your terminal cannot find it. yt-dlp needs ffmpeg for audio extraction, post-processing, and combining separate video and audio streams.

Quick answer

Check whether ffmpeg is available first.

ffmpeg -version

If that command fails, yt-dlp is not the real problem yet. Install ffmpeg and make sure your shell can see it.

Install ffmpeg by platform

# macOS
brew install ffmpeg

# Windows
winget install Gyan.FFmpeg

# Ubuntu / Debian
sudo apt install ffmpeg

After installation, close and reopen the terminal before testing again. PATH updates often do not appear in an old shell session.

Why yt-dlp needs ffmpeg

• merging separate best-video and best-audio streams
• converting extracted audio to MP3 or another format
• remuxing or post-processing media outputs

If you only download a simple combined stream, you might avoid ffmpeg for a while. But as soon as you want better quality or audio conversion, you usually need it.

Most common causes

• ffmpeg was never installed
• it was installed, but not added to PATH
• the terminal needs to be restarted
• you have multiple shells or environments and installed it in one but not the one running yt-dlp

The mistake to avoid

Do not keep changing yt-dlp flags while ffmpeg is still unavailable. If ffmpeg -version fails, fix that first. Otherwise you are debugging the wrong layer.

Later

Need a cleaner workflow after the fix?

Solve the issue first. If yt-dlp becomes part of a repeated process afterward, Importly is worth a look when you want the workflow to be more organized and less manual.

Keep Importly in mind