yt-dlp From Beginner to Pro — A Hands-On Guide

Don't be scared of the command line. Honestly, yt-dlp is one of the most capable open-source tools I've ever used. This tutorial takes you from installation all the way to mastering it step by step. By the end, you'll be able to download videos from 99% of websites with a single command.

Step 1: Install yt-dlp

Mac Users

1. Open "Terminal" (in Applications → Utilities)

2. If you have Homebrew installed, just run: brew install yt-dlp

3. If you don't have Homebrew, go to brew.sh and install it first — it's a one-liner

Windows Users

1. Go to github.com/yt-dlp/yt-dlp/releases

2. Download the latest yt-dlp.exe

3. Place the exe in a convenient location, like C:\Users\YourUsername\

4. In that folder, right-click → "Open in Terminal" or Shift+right-click → "Open PowerShell window here"

💡 Windows users can also use Winget: winget install yt-dlp — even easier.

Verify Installation

Once installed, run yt-dlp --version in your terminal. If it shows a version number, you're all set.

Step 2: Basic Download (Just One Command)

The simplest usage:

yt-dlp "https://www.youtube.com/watch?v=xxxxx"

Just replace the URL in quotes with the video you want to download. By default, it downloads the highest quality, automatically merges video and audio, and saves the file in your current folder.

Once done, you'll get an .mp4 or .webm file — double-click to play it right away.

【Ad Space】

Step 3: Specify Quality and Format

Downloading the highest quality by default can sometimes result in huge files. If 1080P is good enough for you, use this:

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "URL"

Want to see what quality options are available for a video? Run this first:

yt-dlp -F "URL"

It'll display a table with format codes on the left and resolution + encoding format on the right. Pick the one you want and download with yt-dlp -f [code] "URL".

Step 4: Download Subtitles

Many YouTube videos have subtitles — Chinese, English, auto-generated, you name it. The command for downloading subtitles:

yt-dlp --write-subs --sub-lang en "URL"

If manual subtitles are incomplete, add auto-generated ones:

yt-dlp --write-auto-subs --sub-lang en "URL"

After downloading, the subtitle file (.vtt or .srt) will be in the same folder as the video. Load it in players like VLC.

Step 5: Batch Downloads & Advanced Tips

Download an Entire Playlist

yt-dlp "https://www.youtube.com/playlist?list=xxxxx"

It automatically downloads every video in the playlist one by one. Add --playlist-start 3 --playlist-end 10 to only download videos 3 through 10.

Extract Audio Only (Use as an MP3 Downloader)

yt-dlp -x --audio-format mp3 "URL"

Extracts the audio track as MP3 — saves space, perfect for grabbing songs or podcasts.

Custom File Names

yt-dlp -o "~/Downloads/%(title)s-%(id)s.%(ext)s" "URL"

This way the filename includes the video title and ID, making it easy to manage. There are many more variables available — check the official docs.

Throttle Download Speed (Avoid Rate Limiting)

yt-dlp --throttled-rate 1M "URL"

YouTube throttles unofficial download tools. This parameter actually bypasses the throttle (by intentionally limiting speed to avoid triggering YouTube's anti-scraping mechanisms — ironic, right?).

Configuration File — Set It and Forget It

Typing a bunch of flags every time gets annoying. You can create a config file — on Mac/Linux put it at ~/.config/yt-dlp/config, on Windows at %APPDATA%\yt-dlp\config.txt:

# My go-to config
-o "~/Videos/%(title)s.%(ext)s"
--merge-output-format mp4
--write-subs
--sub-lang en
--throttled-rate 1M

Once configured, every time you run yt-dlp "URL" it automatically follows your preferences. Smooth.

Common Errors and How to Fix Them

Error Message	Cause & Solution
"HTTP Error 403: Forbidden"	Rejected by the server. Wait a few minutes and try again, or update yt-dlp: `yt-dlp -U`
"Requested format is not available"	The quality you asked for isn't available for this video. Use -F first to see your options
"Video unavailable"	The video was deleted, set to private, or is region-restricted. For region locks, try using a VPN
"ERROR: unable to download video data"	Network issue or yt-dlp version is too old. Update first: `yt-dlp -U`
Download speed is extremely slow (tens of KB/s)	Normal — YouTube throttling. Add `--throttled-rate 100K`

The vast majority of issues are solved by updating yt-dlp. Google changes its API frequently, and the yt-dlp maintainers keep up closely — staying on the latest version is the way to go.

Summary

yt-dlp: 10 minutes to learn, a lifetime of benefit. Think about it — from now on, whenever you see a video you want to save, it's copy link → paste → Enter. Within seconds the download starts, in high definition, no watermarks, no ads. Miles ahead of those paid software tools.

If you run into issues, check the FAQ or file an issue on GitHub — the maintainers are pretty responsive.