SysTutorials

Download YouTube Videos with yt-dlp

· Eric Ma · updated April 11, 2026

The most reliable way to download YouTube videos is yt-dlp, a maintained fork of youtube-dl that handles modern YouTube changes. It works on Linux, macOS, and Windows.

Installation

Linux (Debian/Ubuntu):

sudo apt install yt-dlp

Linux (Fedora/RHEL):

sudo dnf install yt-dlp

macOS:

brew install yt-dlp

Windows or any system with Python 3.9+:

pip install yt-dlp

Keep it updated to handle YouTube’s frequent API changes:

pip install --upgrade yt-dlp

Basic Download

Download a video in best available quality:

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

This merges video and audio into a single file (typically .webm or .mp4).

Common Downloads

Audio only (MP3):

yt-dlp -x --audio-format mp3 https://www.youtube.com/watch?v=VIDEO_ID

List available formats:

yt-dlp -F https://www.youtube.com/watch?v=VIDEO_ID

This shows resolution, bitrate, and format codes. Example output:

[youtube] Extracting video information
Format ID  | Extension | Resolution | FPS | Video Codec    | Audio Codec | Audio Bitrate
18         | mp4       | 640x360    |     | h.264          | aac         | 96k
22         | mp4       | 1280x720   |     | h.264          | aac         | 128k

Download specific quality (e.g., 1080p with best audio):

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" https://www.youtube.com/watch?v=VIDEO_ID

Download entire playlist:

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

Custom filename:

yt-dlp -o "%(uploader)s - %(title)s.%(ext)s" https://www.youtube.com/watch?v=VIDEO_ID

Useful template variables:

Limit download speed (useful on shared connections):

yt-dlp -r 2M https://www.youtube.com/watch?v=VIDEO_ID

Download to specific directory:

yt-dlp -o ~/Videos/%(title)s.%(ext)s https://www.youtube.com/watch?v=VIDEO_ID

Age-Restricted and Authenticated Content

For age-restricted videos, pull authentication from your browser:

yt-dlp --cookies-from-browser firefox https://www.youtube.com/watch?v=VIDEO_ID

Works with firefox, chrome, chromium, edge, and others. Make sure you’re logged in to YouTube in that browser first.

Live Streams

Record a live stream as it happens:

yt-dlp --wait-for-video 3600 https://www.youtube.com/watch?v=VIDEO_ID

This polls for the scheduled stream every 3600 seconds until it starts; the value is the retry interval, not a total wait limit. Once recording begins, it continues until the stream ends.

For already-completed streams (VODs), download normally:

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

Batch Processing

Create a file urls.txt with one URL per line:

https://www.youtube.com/watch?v=ID1
https://www.youtube.com/watch?v=ID2
https://www.youtube.com/playlist?list=PLAYLIST_ID

Download all at once:

yt-dlp -a urls.txt

Subtitle Handling

Download subtitles automatically:

yt-dlp --write-subs https://www.youtube.com/watch?v=VIDEO_ID

Download specific subtitle language:

yt-dlp --write-subs --sub-langs en https://www.youtube.com/watch?v=VIDEO_ID

Download all available subtitles:

yt-dlp --write-subs --sub-langs all https://www.youtube.com/watch?v=VIDEO_ID

Configuration File

Create persistent settings in ~/.config/yt-dlp/config:

# Best quality, merged into MP4
-f bestvideo+bestaudio/best
--merge-output-format mp4

# Save location and naming
-o ~/Videos/%(uploader)s/%(title)s.%(ext)s

# Auto-download subtitles
--write-subs
--sub-langs en

# Metadata
--write-info-json
--write-description

# Throttle on slow connections
-r 1.5M

Now run just yt-dlp URL and all settings apply automatically.

Post-Processing with FFmpeg

Convert or re-encode during download (requires ffmpeg installed):

yt-dlp --postprocessor-args "-c:v libx265 -crf 28" https://www.youtube.com/watch?v=VIDEO_ID

This re-encodes with H.265 (HEVC) at quality 28 for smaller file sizes. Higher CRF values = smaller files but lower quality.

Skip re-encoding and just remux to MP4:

yt-dlp -f bestvideo+bestaudio --merge-output-format mp4 https://www.youtube.com/watch?v=VIDEO_ID

Troubleshooting

“No video found” or extraction fails: Update yt-dlp first — YouTube changes frequently:

pip install --upgrade yt-dlp

Check if the video is still available, region-restricted, or requires login. Age-restricted videos need the --cookies-from-browser flag.

Slow downloads: Check your connection speed. Rate-limit with -r if you’re on a shared network. Download during off-peak hours if possible.

ffmpeg errors: If post-processing fails, install ffmpeg:

sudo apt install ffmpeg  # Debian/Ubuntu
sudo dnf install ffmpeg  # Fedora
brew install ffmpeg      # macOS

Permission denied when saving: Verify the output directory exists and you have write permissions:

mkdir -p ~/Videos
chmod 755 ~/Videos

Why yt-dlp Over Web Services?

Online converters are unreliable, frequently break when YouTube updates, expose your viewing history to third parties, and may contain malware. yt-dlp keeps everything local, transparent, and under your control.

← All posts