The yt-dlp Manual: Grab Videos and Audio From Your Terminal

yt-dlp is a command-line tool that downloads videos and audio from YouTube, Vimeo, Dailymotion, and over a thousand other platforms. It handles format selection, subtitle embedding, audio extraction, metadata tagging, cookie-based authentication, and live stream recording. This page covers the most common yt-dlp commands, organized by task.

Download Videos With yt-dlp

Single video

Pass a URL to grab the highest available quality. yt-dlp fetches the best video and audio streams, then merges them into one file:

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

Full playlist

Prefix each file with its position number using a naming template:

$ yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" \
    "https://www.example.com/playlist?list=PLAYLIST_ID"

Multiple URLs from a text file

Put one URL per line in a plain text file, then pass it with -a:

$ yt-dlp -a urls.txt

Skip already-downloaded files

yt-dlp logs completed video IDs into an archive file and skips them on the next run:

$ yt-dlp --download-archive archive.txt --no-overwrites "PLAYLIST_URL"

Prevent downloading an entire playlist from a short

$ yt-dlp --no-playlist "SHORTS_URL"

Record a live stream

Use MPEG-TS for HLS streams so the file stays usable if the process is interrupted:

$ yt-dlp --hls-use-mpegts "LIVE_STREAM_URL"

Extract Audio With yt-dlp

Rip audio and convert to MP3

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

Keep the original audio codec without re-encoding

$ yt-dlp -x --audio-format best --no-keep-video "URL"

Download Subtitles With yt-dlp

Fetch and embed English captions

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

Split video by chapters

Each chapter marker in the video becomes a separate output file:

$ yt-dlp --split-chapters -o "%(title)s - %(chapter)s.%(ext)s" "URL"

Select Format and Quality in yt-dlp

Use -F to list all available formats for a URL before downloading. Then use -f to pick one:

$ yt-dlp -F "URL"

Command	What it does
yt-dlp -f “bv*+ba” URL	Merges best video with best audio
yt-dlp -f “best[height<=720]” URL	Caps resolution at 720p
yt-dlp -f “mp4” URL	Prefers MP4 container
yt-dlp -f “bv[ext=webm]+ba[ext=m4a]” URL	Pairs a WebM video track with M4A audio
yt-dlp –recode-video mp4 URL	Converts output to MP4 after download

Control Output File Names

Use -o with template variables to set custom paths and names:

$ yt-dlp -o "~/Videos/%(title)s.%(ext)s" "URL"

Prefix the filename with the upload date:

$ yt-dlp -o "%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" "URL"

Embed Metadata and Thumbnails

Write video tags and cover art directly into the output file:

$ yt-dlp --embed-metadata --embed-thumbnail "URL"

For live streams, save the chat as a JSON file alongside the video:

$ yt-dlp --write-chat "LIVE_URL"

Use Cookies for Restricted Content

Age-gated or login-required pages need a valid session cookie. Export cookies from your browser and pass the file:

$ yt-dlp --cookies cookies.txt "URL"

Or let yt-dlp read cookies directly from an installed browser:

$ yt-dlp --cookies-from-browser firefox "URL"

Network and Bandwidth Options

Route traffic through a proxy

$ yt-dlp --proxy socks5://127.0.0.1:9050 "URL"

Use aria2c for parallel segment downloads

Handing off to an external downloader like aria2c can significantly increase speed on large files:

$ yt-dlp --external-downloader aria2c \
    --external-downloader-args "-x 16 -k 1M" "URL"

Limit download speed

$ yt-dlp --limit-rate 500K "URL"

Add random pauses between requests

This reduces the chance of rate-limiting when downloading large playlists:

$ yt-dlp --sleep-interval 5 --max-sleep-interval 10 "URL"

Automate With a yt-dlp Config File

Place a config file at ~/.config/yt-dlp/config to apply options automatically on every run. One flag per line:

--format bv*+ba
--merge-output-format mp4
--embed-thumbnail
--embed-metadata
--write-subs
--sub-lang en
--output ~/Videos/%(title)s.%(ext)s

To use a different config path, pass --config-location /path/to/config.

Troubleshoot and Update yt-dlp

Command	Purpose
yt-dlp –verbose URL	Print full debug output
yt-dlp –ignore-errors URL	Skip failed items and continue
yt-dlp –no-check-certificate URL	Bypass SSL verification (insecure)
yt-dlp -U	Install the latest available release

yt-dlp Command Quick Reference

Command	Purpose
yt-dlp URL	Download best quality audio and video
yt-dlp -x –audio-format mp3 URL	Extract audio, convert to MP3
yt-dlp -x –audio-format best –no-keep-video URL	Extract audio without re-encoding
yt-dlp –write-subs –sub-lang en –embed-subs URL	Fetch and embed English captions
yt-dlp –write-auto-subs URL	Pull auto-generated captions
yt-dlp -f “bv*+ba” URL	Merge top video and audio streams
yt-dlp -F URL	List all available formats
yt-dlp -f “best[height<=720]” URL	Cap resolution at 720p
yt-dlp -a urls.txt	Process URLs from a text file
yt-dlp –download-archive archive.txt PLAYLIST_URL	Skip already-downloaded items
yt-dlp –split-chapters -o “%(title)s – %(chapter)s.%(ext)s” URL	Create one file per chapter
yt-dlp –embed-metadata –embed-thumbnail URL	Write tags and cover art into output
yt-dlp –cookies cookies.txt URL	Access restricted content via cookies
yt-dlp –cookies-from-browser firefox URL	Read cookies from Firefox
yt-dlp –proxy socks5://127.0.0.1:9050 URL	Route through a SOCKS5 proxy
yt-dlp –limit-rate 500K URL	Cap throughput at 500 KB/s
yt-dlp –hls-use-mpegts URL	Record HLS streams with MPEG-TS
yt-dlp –ignore-errors URL	Skip failed items without stopping
yt-dlp –verbose URL	Print full debug output
yt-dlp -U	Update to the latest release