Skip to content

Start typing. Errors match on their exact yt-dlp output.

↑ ↓ to move, ↵ to open esc to close

Install ffmpeg for yt-dlp on Windows, macOS and Linux

Tested on yt-dlp 2026.07.28 Updated

Quick answer

ffmpeg is a separate program, not a Python package, and yt-dlp needs it to merge the separate video and audio streams that every quality above 720p is served as. One command per platform:

Windows 
winget install Gyan.FFmpeg
macOS 
brew install ffmpeg
Debian and Ubuntu 
sudo apt install ffmpeg libavcodec-extra

What breaks without it

Not everything — which is why the problem is so often misdiagnosed. yt-dlp still runs, still downloads, still reports success. It just declines to choose any format that would need merging.

TaskWithout ffmpeg
1080p and aboveSilently downgraded to 360p
Merging video and audioAborts with an error
Extracting audio to mp3Fails
Embedding subtitles or thumbnailsFails
Converting containersFails
SponsorBlock removalFails
A 360p downloadWorks fine

That last row is the trap. A quick test succeeds, so ffmpeg looks unnecessary — until the quality turns out to be wrong. That is the whole of stuck at 360p.

Windows

winget, Scoop or Chocolatey all handle PATH, which is the step manual installs get wrong:

bash 
winget install Gyan.FFmpeg
scoop install ffmpeg
choco install ffmpeg          # elevated prompt

Installing by hand: download a build, extract it somewhere permanent such as C:\ffmpeg, and either add C:\ffmpeg\bin to PATH or point yt-dlp at it:

the folder, not the exe 
yt-dlp --ffmpeg-location "C:\ffmpeg\bin" "URL"

Simplest of all on Windows: put ffmpeg.exe and ffprobe.exe in the same folder as yt-dlp.exe. yt-dlp looks there first, and nothing else needs changing.

macOS

bash 
brew install ffmpeg
sudo port install ffmpeg    # MacPorts

Homebrew's build includes the encoders yt-dlp expects. If brew is not installed, the macOS page covers it — and covers the Apple silicon PATH problem that makes a successful install look like a failed one.

Linux

bash 
sudo apt install ffmpeg libavcodec-extra   # Debian, Ubuntu
sudo dnf install ffmpeg                    # Fedora — needs RPM Fusion
sudo pacman -S ffmpeg                      # Arch
sudo zypper install ffmpeg                 # openSUSE

Unlike yt-dlp, the packaged ffmpeg is fine — it is not chasing a moving target, so a distribution build from last year still does the job.

On minimal and container images, ffmpeg alone can lack the MP3 encoder, and audio extraction then fails with ffmpeg exited with code 1. That is what libavcodec-extra is for. On Fedora and RHEL, enable RPM Fusion first — ffmpeg is not in the default repositories.

Android and Docker

Termux 
pkg install ffmpeg
Dockerfile 
RUN apk add --no-cache ffmpeg     # Alpine
RUN apt-get update && apt-get install -y ffmpeg   # Debian-based

Full setups on the Termux and Docker pages.

Verifying the pairing

Two separate questions: is ffmpeg installed, and can yt-dlp see it. Both matter, and the second is the one that fails.

1. is it installed 
ffmpeg -version
ffprobe -version
2. can yt-dlp see it 
yt-dlp --verbose --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"

The verbose header lists the detected ffmpeg and ffprobe versions. not present there, while your shell prints a version, means the two are looking at different PATHs — a terminal opened before the install, or a scheduled task with no environment. Full diagnosis on the ffmpeg not found page.

Making the location permanent

Rather than typing --ffmpeg-location every time, put it in your config file:

%APPDATA%\yt-dlp\config on Windows, ~/.config/yt-dlp/config elsewhere 
--ffmpeg-location C:\ffmpeg\bin

A quick end-to-end check

This downloads a nineteen-second video at merged quality. If it produces one file above 360p, everything is wired up:

bash 
yt-dlp -f "bv*+ba/b" --merge-output-format mp4 "https://www.youtube.com/watch?v=jNQXAC9IVRw"

Frequently asked

Do I really need ffmpeg?
For anything above 720p on YouTube, yes. High-quality video and audio are served as separate streams and something has to join them. Without ffmpeg yt-dlp silently falls back to the best pre-merged file, which is 360p.
Which build should I download?
The yt-dlp project publishes builds tested against yt-dlp at github.com/yt-dlp/FFmpeg-Builds. They include patches for issues that affect this exact workflow. A generic build usually works; that one is known to.
What is ffprobe and do I need it too?
ffprobe inspects media files, and yt-dlp uses it before postprocessing. It ships alongside ffmpeg in every normal distribution — you only end up without it by copying a single ffmpeg binary out of an archive.
Can I put ffmpeg next to yt-dlp instead of on PATH?
Yes. yt-dlp looks in its own directory first. Dropping ffmpeg.exe and ffprobe.exe beside yt-dlp.exe works with no PATH changes at all, which is handy for a portable install on a USB stick.

Related