What do you want
Audio-only extracts the soundtrack and drops the video stream.
yt-dlp Options Reference
Written against yt-dlp 2026.07.21. Options are added and renamed between releases, so check yours with yt-dlp --version.
Basics
Video and quality
-f FORMAT
--format
Maximum quality
Caps the height. yt-dlp still picks the best stream at or below it.
-f FORMAT
--format
Custom format selector
Overrides the quality dropdown. For people who already know the format syntax.
Examples
-f "bv*[vcodec^=av01]+ba"-f "b[filesize<50M]"
--merge-output-format FORMAT
needs ffmpeg
Container
The file type separate video and audio streams are merged into.
--remux-video FORMAT
needs ffmpeg
Remux into
Repackages the streams without re-encoding. Fast and lossless.
--recode-video FORMAT
needs ffmpeg
Re-encode into
Re-encodes the video. Slow and lossy — only when remuxing will not do.
Audio
--audio-format FORMAT
needs ffmpeg
Audio format
The file the audio is converted to.
--audio-quality QUALITY
needs ffmpeg
Audio quality
VBR gives the best size-to-quality ratio; fixed bitrates are more predictable.
Subtitles
Subtitles
Embedding puts them inside the video; saving writes a separate .srt next to it.
Subtitle languages
Comma separated. Use all for every available language.
Examples
--sub-langs "en,vi"--sub-langs "en.*,ja"--sub-langs all
Auto-generated subtitles
Include machine-generated captions when no human ones exist.
Playlists and channels
Playlist handling
What to do when the URL belongs to both a video and a playlist.
-I ITEM_SPEC
--playlist-items
Which items
Ranges and lists both work, for example 1-10,15 or -5::2 for every second item from the end.
Examples
-I 1:5-I "1,3,7-10"-I "-5::2"
Archive file
Records what has been downloaded so re-running skips it. The way to keep a channel in sync.
Sections and chapters
--download-sections REGEX
needs ffmpeg
Download only part of it
A time range like *00:01:30-00:03:00, or a chapter name. The leading asterisk means it is a timestamp.
Examples
--download-sections "*00:01:30-00:03:00"--download-sections "intro"
--split-chapters
needs ffmpeg
Split into chapters
Writes one file per chapter instead of a single long one.
Metadata and artwork
--embed-thumbnail
needs ffmpeg
Embed thumbnail
Uses the video thumbnail as cover art.
--embed-metadata
needs ffmpeg
Embed metadata
Writes title, uploader and date into the file itself.
--embed-chapters
needs ffmpeg
Embed chapters
Adds chapter markers your player can jump between.
Save thumbnail file
Writes the cover image next to the video.
Save description
Writes the description to a .description file.
Save metadata JSON
Writes everything yt-dlp knows about the video to a .info.json file.
SponsorBlock
--sponsorblock-remove CATS
needs ffmpeg
Remove segments
Cuts community-marked segments out of the file using SponsorBlock data.
Mark segments as chapters
Keeps the segments but marks them, so you can skip them yourself.
Files and folders
-o [TYPES:]TEMPLATE
--output
File name template
Field names go in %(...)s. Slashes create folders.
Examples
-o "%(title)s.%(ext)s"-o "%(playlist_index)02d - %(title)s.%(ext)s"
-P [TYPES:]PATH
--paths
Download folder
Where files are written. Combine with the template above for subfolders.
Safe (ASCII) file names
Strips accents, spaces and anything a stubborn filesystem might reject.
Windows-safe names
Removes characters Windows refuses even when running elsewhere.
Trim names to
Maximum file name length in characters.
Overwrite existing files
Replaces files that are already there.
-w
--no-overwrites
Never overwrite
Skips anything already downloaded.
-c
--continue
Resume partial downloads
Picks up where an interrupted download stopped.
Filters
Uploaded after
YYYYMMDD, or a relative date like now-1month.
Examples
--dateafter 20240101--dateafter now-1month
Uploaded before
YYYYMMDD, or a relative date.
Minimum size
Skips anything smaller. Accepts 5M, 500K and similar.
Maximum size
Skips anything larger.
Stop after
Number of files to download before stopping.
Network
-r RATE
--limit-rate
Speed limit
For example 2M or 500K. Useful when you need the rest of your bandwidth.
-N N
--concurrent-fragments
Parallel fragments
Speeds up fragmented streams. Four is a sensible starting point.
-R RETRIES
--retries
Retries
How many times to retry a failed piece. infinite is allowed.
Proxy
HTTP, HTTPS or SOCKS proxy URL.
Bypass geo-restriction
Fakes the request origin. Works on some sites, not all.
Impersonate a browser
Makes requests look like a real browser. The usual fix for sudden 403 errors.
Login and cookies
Cookies from browser
Reads your logged-in session directly. Needed for private, age-restricted or members-only content.
Cookies file
A Netscape-format cookies.txt exported from your browser.
Live streams
Record from the start
Starts a live stream from the beginning instead of the current moment.
Wait for the stream
Polls until a scheduled stream begins. MIN-MAX seconds between checks.
Workarounds
--user-agent UA
deprecated — --add-headers
User agent
Deprecated in favour of --add-headers. Kept because plenty of older guides still use it.
--referer URL
deprecated — --add-headers
Referer
Deprecated in favour of --add-headers.
Extractor arguments
Site-specific switches, for example youtube:player_client=web.
Examples
--extractor-args "youtube:player_client=web,android"