Troubleshooting · macOS

yt-dlp stopped working on your Mac? Here's what actually happened.

It worked yesterday. Today it's command not found, or a wall of Python you didn't ask for. Nothing you did broke it — and it is almost always one of three things.

1. Homebrew moved, and your shell didn't follow

On an Apple Silicon Mac, Homebrew installs everything under /opt/homebrew. On Intel it was /usr/local. If your shell profile came across from an older Mac — Migration Assistant does this silently — it still points at the old place, so the terminal can't see the binary you just installed or updated.

The tell:

zsh: command not found: yt-dlp

Check where your shell is looking:

echo $PATH

If /opt/homebrew/bin isn't in there, add this to ~/.zprofile and open a new terminal:

eval "$(/opt/homebrew/bin/brew shellenv)"

That single line is what Homebrew's own installer prints at the end and most people scroll past.

2. It's the wrong architecture

An Intel build running on an Apple Silicon Mac without Rosetta fails like this:

bad CPU type in executable

This happens when the binary was downloaded by hand from a site that guessed wrong, or when Homebrew itself was installed under Rosetta. Reinstalling the same way reinstalls the same problem. Check which Homebrew you have:

which brew

/opt/homebrew/bin/brew is native. /usr/local/bin/brew on an M-series Mac is the Intel one running under emulation, and everything it installs will be too.

3. The site changed, and yt-dlp hasn't caught up yet

YouTube and the other big sites change how they serve video without notice. When that happens, every downloader on earth breaks at the same moment, and the fix is an upstream release — usually within days, sometimes within hours. Until then, updating won't help because there is nothing to update to.

The tell is an error that mentions the site, not your machine:

ERROR: [youtube] ...: Unable to extract ...

Update first, because you may simply be behind:

yt-dlp -U

or, if Homebrew installed it, brew upgrade yt-dlp. If you're already on the latest release and it still fails, the fix isn't on your Mac yet. The yt-dlp releases page shows what's been fixed and when.

The one that looks like all three: ffmpeg

yt-dlp downloads video and audio as separate streams and needs ffmpeg to join them. If ffmpeg is missing, you get a working download that plays with no sound, or this:

ERROR: ffmpeg not found. Please install or provide the path using --ffmpeg-location

brew install ffmpeg fixes it — and then problem 1 applies to ffmpeg too, so check your PATH again.

If you'd rather never see any of this again

This is what ReelPull is for. It bundles yt-dlp and ffmpeg inside a signed, notarised Mac app, keeps them updated for you, and turns a pasted link into a clip that drops straight into Final Cut Pro or Premiere. The free tier is uncapped and needs no account.

We publish what we've shipped and when, including how long each fix took — so you can see for yourself whether "we keep up" is true before you trust it.

Two related things people hit straight after this one: whether they are allowed to be downloading at all, and why the file that finally downloaded won't import into Final Cut or Premiere.