Skip to content

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

↑ ↓ to move, ↵ to open esc to close

Install yt-dlp on macOS (Homebrew, MacPorts or Binary)

Tested on yt-dlp 2026.07.28 Updated

Quick answer

Homebrew is the short answer, and installing ffmpeg in the same command avoids the most common follow-up problem — without it, downloads are capped at 360p:

bash 
brew install yt-dlp ffmpeg

No Homebrew yet? Install it, then run the two eval lines it prints at the end — skipping those is why the next command says "command not found":

bash 
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Apple silicon and PATH

Homebrew installs to /opt/homebrew on M-series Macs and /usr/local on Intel. Your shell only searches the one its profile names, and on a Mac migrated from an Intel machine the profile often names the wrong one.

This is behind essentially every "installed fine, command not found" report on macOS:

Apple silicon, zsh 
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Then check what the shell actually resolves:

bash 
which yt-dlp
echo $PATH | tr ':' '\n'

The other two routes

MacPorts

bash 
sudo port install yt-dlp ffmpeg

The standalone binary

Updates itself with -U, which puts you a few days ahead of Homebrew on extractor fixes — the gap that matters when YouTube has just changed something:

bash 
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
yt-dlp --version

If macOS refuses to run it, Gatekeeper has quarantined the download. Clear the flag:

bash 
xattr -d com.apple.quarantine /usr/local/bin/yt-dlp

Do not use Apple's Python

macOS ships a Python for its own use. pip install yt-dlp against it either fails with an "externally managed environment" error or, worse, succeeds and installs into a location nothing else looks at.

If you want a pip install, use pipx, which creates an isolated environment per tool:

bash 
brew install pipx
pipx install yt-dlp
pipx upgrade yt-dlp

Certificates

macOS is the platform where certificate verify failed turns up most often, because Python from python.org ships its own trust bundle and does not populate it automatically. If you installed Python that way, run the script it left behind once:

bash 
/Applications/Python\ 3.12/Install\ Certificates.command

Homebrew's Python and the standalone binary do not have this problem.

Keeping it current

Homebrew 
brew upgrade yt-dlp
standalone binary 
yt-dlp -U
yt-dlp --update-to nightly

Homebrew's formula follows releases, not nightlies. When something breaks site-wide, the fix is often already in nightly and not yet in a release — the trade-off is worth understanding once.

Where downloads land

Wherever the terminal is, which after opening Terminal.app is your home folder. Set it once in a config file at ~/.config/yt-dlp/config:

~/.config/yt-dlp/config 
-P ~/Movies/yt-dlp
-o %(title)s.%(ext)s
--embed-metadata
--embed-thumbnail

If it still fails

  • Works in Terminal, not in iTerm. Different shell profiles. Check both ~/.zprofile and ~/.zshrc.
  • Everything downloads at 360p. ffmpeg missing or invisible — the 360p page.
  • Cookie reads prompt endlessly or fail. Keychain permissions. Safari needs Full Disk Access for your terminal; see cookies permission denied.
  • "bad CPU type in executable". An Intel binary on Apple silicon without Rosetta. Download yt-dlp_macos, which is universal.

Frequently asked

zsh: command not found: yt-dlp on an M-series Mac
Homebrew installs to /opt/homebrew on Apple silicon and /usr/local on Intel, and the shell only knows about the one its profile mentions. Running the two eval lines brew printed at install time — and opening a new terminal — fixes it.
Homebrew or the binary?
Homebrew for convenience, the binary for speed of updates. Homebrew's yt-dlp usually trails the release by a few days, which matters exactly when YouTube has broken something and a fix has just shipped.
macOS says the file cannot be opened because it is from an unidentified developer.
Gatekeeper quarantining a downloaded binary. xattr -d com.apple.quarantine on the file clears it. Homebrew installs are not affected.
Should I use the Python that ships with macOS?
No. Apple's Python is for the system and pip installs against it fail or break things. If you want a pip install, install Python through Homebrew first — or use pipx, which handles the isolation for you.

Related