Comprehensive yt-dlp Guide & Reference Cheat Sheet
1. Prerequisites, Installation & System Integration
1.1 Platform-Specific Installation
yt-dlp is a cross-platform command-line media downloader. Depending on your operating system, it can be installed via standalone binary downloads, Python’s package manager (pip), or standard platform package managers.
Windows Installation
You can install yt-dlp using the Windows Package Manager (winget) or by downloading the standalone executable manually.
:: Installation via winget
winget install yt-dlp.yt-dlp
For manual installation:
- Create a directory such as
C:\yt-dlp. - Download
yt-dlp.exe(64-bit standalone binary) from the official GitHub release page and place it intoC:\yt-dlp. - Add
C:\yt-dlpto your SystemPATHenvironment variable via System Properties > Environment Variables.
macOS Installation
On macOS, install yt-dlp using Homebrew:
brew install yt-dlp
Linux Installation
You can download the platform-independent executable or the glibc-bundled standalone binary:
# Option A: Download the platform-independent zipimport executable
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp
/-o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp
# Option B: Download the standalone Linux x86_64 binary (bundled Python runtime)
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_linux
-o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlpAlternatively, install or update yt-dlp in your Python environment via pip:
python3 -m pip install -U yt-dlp
Note on Binary Types & Package Managers: The primary yt-dlp release file (without an extension) is a platform-independent zipimport binary that requires Python 3.10+ pre-installed on the host system. If your environment lacks Python 3.10+, download the standalone binary (yt-dlp_linux for glibc x86_64 or yt-dlp_musllinux for Alpine/musl systems), which includes an embedded Python runtime via PyInstaller.
System package managers (such as Linux apt) often host outdated builds. Because streaming platforms frequently alter their video serving logic, outdated packages quickly suffer from extractor errors. Direct official binary downloads or pip installations are strongly recommended.
1.2 Installing and Integrating FFmpeg
FFmpeg is an essential dependency for yt-dlp. Modern media platforms host high-definition video and audio as separate adaptive streams. FFmpeg is required to merge these streams into a single container without re-encoding, perform format conversions, embed subtitles, and slice video segments.
System Installation Commands
- Windows:
winget install Gyan.FFmpeg
(Alternatively, extract ffmpeg.exe from the Gyan.dev git full build ZIP directly into your yt-dlp directory).
- macOS:
brew install ffmpeg
- Linux (Debian/Ubuntu):
sudo apt install ffmpeg
Official FFmpeg Builds: For headless server environments or custom Linux setups, the project maintains official, optimized FFmpeg builds at yt-dlp/FFmpeg-Builds on GitHub, which offer maximum compatibility with yt-dlp post-processing operations.
Manual Path Override
If FFmpeg is installed outside your system PATH, specify its binary directory directly:
yt-dlp --ffmpeg-location /path/to/ffmpeg "URL"
1.3 Post-Installation Verification & Maintenance
Verify that both yt-dlp and ffmpeg are available in your shell environment:
yt-dlp --version
ffmpeg -version
yt-dlp -F "https://www.youtube.com/watch?v=BaW_jenozKc" Update Maintenance Matrix
Installation Method | Update Command |
Standalone Binary |
|
Python Pip |
|
Homebrew (macOS) |
|
Winget (Windows) |
|
Switching Release Channels
yt-dlp offers three release channels: stable (monthly tagged releases), nightly (daily builds recommended for rapid extractor fixes), and master (canary builds compiled from every main branch commit).
# Switch binary to the recommended nightly development channel
yt-dlp --update-to nightly
# Switch binary to the master branch channel
yt-dlp --update-to master
# Pin or downgrade binary to a specific version tag
yt-dlp --update-to stable@2023.07.06
2. Fundamental Downloading & Format Inspection
2.1 Basic Video Downloading
To execute a default download, pass the target video URL enclosed in double quotes.
yt-dlp "https://www.youtube.com/watch?v=YE7VzlLtp-4"
Internal Download Execution Workflow
When executed, yt-dlp runs through the following sequence:
- Connects to the host site and extracts available video and audio metadata.
- Analyzes available streams and filters candidate stream identifiers.
- Selects the optimal video-only stream and audio-only stream based on quality rules.
- Downloads both selected streams concurrently into temporary partial files.
- Invokes FFmpeg to multiplex (mux) the video and audio streams into a unified container file (e.g.,
.mp4or.mkv). - Cleans up intermediate temporary stream files from the working directory.
2.2 Listing and Analyzing Formats (-F)
Inspect available video and audio streams without downloading the actual media using the -F (or --list-formats) flag.
yt-dlp -F "https://www.youtube.com/watch?v=YE7VzlLtp-4"
Representative Output Format Table
ID EXT RESOLUTION FPS │ FILESIZE TBR PROTO │ VCODEC VBR ACODEC ABR
─────────────────────────────────────────────────────────────────────────────────────────
sb0 mhtml 48x27 1 │ mhtml │ images
139 m4a audio only │ 1.58MiB 49k https │ audio only mp4a.40.5 49k
140 m4a audio only │ 4.19MiB 130k https │ audio only mp4a.40.2 130k
137 mp4 1920x1080 30 │ 43.11MiB 1344k https │ avc1.640028 1344k video only
248 webm 1920x1080 30 │ 28.08MiB 875k https │ vp9 875k video only
18 mp4 640x360 30 │ ~12.50MiB 500k https │ avc1.42001E mp4a.40.2
Field Description Breakdown
- ID: Extractor format code used for manual selection via
-f. - EXT: Standard container format (e.g.,
mp4,webm,m4a). - RESOLUTION / FPS: Spatial dimensions and frame rate (
audio onlyindicates missing video track). - FILESIZE / TBR: Total file size and Total Bitrate (kbps).
- VCODEC / VBR: Video codec (e.g.,
avc1,vp9) and bitrate.video onlyindicates missing audio track. - ACODEC / ABR: Audio codec (e.g.,
mp4a.40.2,opus) and bitrate.audio onlyindicates pure audio track.
2.3 Manual Format Selection by Code (-f)
Select specific format IDs from the -F output table to override automatic stream selection.
# Download a single combined pre-merged format (ID 22)
yt-dlp -f 22 "URL"
# Merge specific video stream ID 137 with audio stream ID 140
yt-dlp -f 137+140 "URL"
# Fallback chain: attempt format 22, fallback to 17, then fallback to 18
yt-dlp -f 22/17/18 "URL"
3. Quality Control & Advanced Format Selection
3.1 Default Selection Rules & Fallbacks
yt-dlp evaluates stream priority differently than older downloaders such as youtube-dl.
Default Format Selector: bv*+ba/b By default, yt-dlp selects the best video stream (bv*) plus the best audio stream (ba). If a combined pre-merged video/audio stream (/b) provides superior quality to separate video and audio options, it downloads that combined stream instead.
- Multistream Behavior: Enabling
--audio-multistreamsshifts default selection to-f bestvideo+bestaudio/best. - Stdout Streaming: Directing output to
stdout(-o -) defaults to-f best/bestvideo+bestaudioif FFmpeg is unavailable.
3.2 Quality Capping and Resolution Limits
Constrain output quality and file extensions using bracketed stream conditions.
# Cap maximum resolution at 1080p
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" "URL"
# Force strict MP4/M4A input containers with explicit MP4 output muxing
yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]" --merge-output-format mp4 "URL"
# Grouped selection syntax: filter pre-merged mp4 or webm streams under 480p
yt-dlp -f "(mp4,webm)[height<480]" "URL"
3.3 Format Sorting Strategies (-S / --format-sort)
The -S flag alters stream selection priority without requiring complex -f conditional syntax. By default, format fields are evaluated in descending order, and multiple sort criteria can be chained using a comma-separated string (e.g., -S "res:720,vcodec:h264,fps").
Format Sort Fields and Modifiers Matrix
Sort Field | Description | Example Usage |
| Resolution (evaluated by smallest dimension for vertical video support). |
|
| Frame rate. |
|
| Exact or estimated file size. |
|
| Bitrate (total, video, or audio). |
|
| Video codec ( |
|
| Audio codec ( |
|
| Extension preference ( |
|
| Transfer protocol ( |
|
Modifier Syntax Rules
+(Prefix): Reverses sorting order to ascending (e.g.,+sizeselects smallest file).:(Suffix): Sets a hard preference threshold (e.g.,res:1080).~(Suffix): Prefers the value closest to the target parameter (e.g.,filesize~50M).
3.4 Advanced Format Filtering Parameters
Filters inside square brackets [KEY OPERATOR VALUE] inspect stream metadata attributes.
- Numeric Fields:
filesize,filesize_approx,width,height,tbr,abr,vbr,fps,asr,audio_channels. - String Fields:
ext,acodec,vcodec,container,protocol,language,format_id. - Available Operators:
<,<=,>,>=,=,!=,^=(starts with),$=(ends with),*=(contains),~=(regex match),!(negation).
# Select up to 720p video (or missing height field) with total bitrate > 500 kbps
yt-dlp -f "bv[height<=?720][tbr>500]+ba" "URL"
# Extract all audio-only streams matching filter
yt-dlp -f "all[vcodec=none]" "URL"
4. Audio Extraction & Media Processing
4.1 Standard Audio Extraction (-x)
The -x (or --extract-audio) option instructs yt-dlp to discard the video track and extract the standalone audio stream.
yt-dlp -x "https://www.youtube.com/watch?v=YE7VzlLtp-4"
Stream Copying vs. Re-encoding: By default, -x extracts the source audio format directly (e.g., .opus or .m4a) without re-encoding. This process completes quickly with zero generational quality loss.
4.2 Audio Format Conversion & Quality Flags
To force conversion of the extracted audio stream into a specific format, combine -x with --audio-format and --audio-quality.
- Supported
--audio-formatTargets:best(default),aac,alac,flac,m4a,mp3,opus,vorbis,wav. - Quality Settings (
--audio-quality): Accepts values from0(highest VBR quality) to10(lowest VBR quality), or explicit bitrates like128Kor320K(default is5).
# Convert audio stream to MP3 at variable bitrate quality 0
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"
# Extract and wrap audio stream in lossless FLAC container
yt-dlp -x --audio-format flac "URL"
Lossy-to-Lossy Quality Warning: Converting compressed web audio (such as YouTube Opus or AAC) into MP3 forces a secondary lossy encoding pass, causing minor audio degradation. To retain maximum fidelity, use --audio-format best or keep native M4A/Opus containers unless target playback devices strictly require MP3.
4.3 Cover Art, Metadata, and File Preservation Flags
# Tagged MP3 download pipeline with embedded artwork and video retention
yt-dlp -x \
--audio-format mp3 \
--audio-quality 0 \
--embed-thumbnail \
--embed-metadata \
-k "URL"
-k(--keep-video): Retains the original intermediate video file on disk alongside the converted audio output.--embed-thumbnail: Embeds cover art directly into audio tags (requiresmutagenorAtomicParsley).--embed-metadata: Writes title, artist, uploader, and date metadata into the output file.
5. Playlist, Channel, and Batch Downloads with Archive Logging
5.1 Playlist Range Control and Slicing
Filter and select specific items within remote playlists using range limits or Python slice syntax.
# Download playlist items 1 through 5
yt-dlp --playlist-start 1 --playlist-end 5 "PLAYLIST_URL"
# Index slicing syntax (-I or --playlist-items): items 1
# to 3, item 7, and every second item from item 11 onward
yt-dlp -I 1:3,7,11::2 "PLAYLIST_URL"
# Download every second video in a playlist
yt-dlp -I 1::2 "PLAYLIST_URL"
# Process playlist entries in reverse order
yt-dlp --playlist-reverse "PLAYLIST_URL"
# Process playlist entries in randomized order
yt-dlp --playlist-random "PLAYLIST_URL"5.2 Channel Ingestion and Batch File Processing (-a)
Process complete channel feeds or read target URLs from a batch text file using -a or --batch-file.
# Sample batch file: urls.txt
# Lines starting with '#', ';', or ']' are treated as comments
https://www.youtube.com/watch?v=YE7VzlLtp-4
https://www.youtube.com/watch?v=ptd1NN40vMw
# Comment line: skip unreachable URL
;https://www.youtube.com/watch?v=invalid_id
https://www.youtube.com/@TheLinuxFoundation
Execute batch downloads with:
yt-dlp -a urls.txt
5.3 Preventing Duplicate Downloads (--download-archive)
For continuous backup automation or channel archiving, use --download-archive to record processed video IDs.
yt-dlp --download-archive archive.txt --break-on-existing "https://www.youtube.com/@ChannelName"
Operational Breakdown
archive.txtMechanics:yt-dlplogs extracted video IDs to this text file upon successful download. Subsequent executions match extracted IDs againstarchive.txtand skip previously downloaded videos.--break-on-existing: Terminates playlist processing as soon as an archived ID is encountered, reducing redundant API requests when scanning updated channels.
6. Output Template Formatting (-o) & Path Control (-P)
6.1 Output Template Syntax & Variables
The -o flag controls filename patterns using Python string formatting: %(name[.keys][addition][>strf][,alternate][&replacement][|default])type
Core Metadata Template Keys
Template Key | Description | Sample Output Value |
| Sanitized video title. |
|
| Unique extractor ID. |
|
| Output container extension. |
|
| UTC upload date ( |
|
| Custom |
|
| Uploader/channel display name. |
|
| Parent playlist name. |
|
| Index position in playlist. |
|
| Spatial resolution. |
|
| Media duration formatted as |
|
Filename Sanitization Flags
--restrict-filenames: Restricts output filenames strictly to ASCII characters, eliminating spaces and ampersands.--windows-filenames: Forces filenames to comply with Windows filesystem naming rules.
6.2 Structuring Directory Trees
Output templates accept directory path separators to organize downloads based on extracted metadata:
# Save playlist items into a directory named after the playlist
yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"
# Group downloads by Uploader and Upload Year
yt-dlp -o "%(uploader)s/%(upload_date>%Y)s/%(title)s.%(ext)s" "URL"
# Organize episodic shows into Series/Season/Episode structures
yt-dlp -o "%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" "URL"
6.3 Advanced Path Assignment (-P / --paths)
The -P flag sets output and temporary download directories separately from filename templates.
# Set final output path, separate temp path, and subtitle target location
yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs"
-o "%(uploader)s/%(title)s.%(ext)s" --write-subs "URL"7. Subtitles, Metadata, Cover Art, and SponsorBlock Integration
7.1 Subtitle Extraction and Embedding
# List available subtitle languages and formats
yt-dlp --list-subs "URL"
# Subtitle retrieval and container embedding pipeline
yt-dlp \
--write-subs \
--write-auto-subs \
--sub-langs "en.*,ja" \
--convert-subs srt \
--embed-subs "URL"
--write-subs/--write-auto-subs: Downloads manual or automatically generated captions.--sub-langs: Accepts language tags or regex matching patterns (e.g.,"en.*,ja"matches all English regional variants and Japanese).--convert-subs: Converts downloaded captions intosrt,vtt,ass, orlrcformats.--embed-subs: Embeds subtitles directly into.mp4,.webm, or.mkvcontainers.
7.2 Metadata Tagging & In-Flight Modifications
# Embed primary metadata tags into media container
yt-dlp --embed-metadata "URL"
# Parse metadata field: interpret Title as "Artist - Title"
yt-dlp --parse-metadata "title:%(artist)s - %(title)s" "URL"
# Replace spaces and underscores in title and uploader fields with hyphens
yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-" "URL"
7.3 Thumbnail Operations
# Download thumbnail, convert to JPG, and embed as cover art in an MP3 file
yt-dlp -x --audio-format mp3 --write-thumbnail --convert-thumbnails jpg --embed-thumbnail "URL"
7.4 SponsorBlock Integration
yt-dlp integrates with the SponsorBlock API to mark or cut sponsored segments, intros, and filler content during download.
Category Restrictions & Rules
- Available Categories:
sponsor,intro,outro,selfpromo,preview,filler,interaction,music_offtopic,hook,poi_highlight,chapter,all,default. - Marking vs. Removing: The
poi_highlightandchaptercategories are supported only for--sponsorblock-markand cannot be passed to--sponsorblock-remove. - Default Target Resolution: Passing
defaultto--sponsorblock-removeevaluates toall,-filler.
# Create internal chapters for sponsor segments while skipping preview markers
yt-dlp --sponsorblock-mark all,-preview "URL"
# Cut sponsor and intro segments out of the media file (requires FFmpeg)
yt-dlp --sponsorblock-remove "sponsor,intro" "URL"
8. Authentication Mechanisms
8.1 Browser Cookie Extraction (--cookies-from-browser)
Extract session cookies directly from installed web browsers to download private, age-restricted, or member-only content.
Supported Browsers
brave, chrome, chromium, edge, firefox, opera, safari, vivaldi, whale.
Command Syntax
--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]
- Keyring Identifiers:
basictext,gnomekeyring,kwallet,kwallet5,kwallet6. - Firefox Container: The
CONTAINERsuffix applies exclusively to Firefox profiles (ornoneto disable container checking).
# Extract cookies from default Chrome browser installation
yt-dlp --cookies-from-browser chrome "URL"
# Extract cookies from Firefox profile using a specific keyring
yt-dlp --cookies-from-browser firefox+gnomekeyring "URL"
Linux Keyring Security Note: On Linux systems decrypting Chromium-based browser cookies, yt-dlp requires the Python secretstorage package to access system keyrings (gnomekeyring or kwallet).
8.2 File-Based Cookie Usage (--cookies)
For headless server setups or unsupported browser environments, export cookies to a Netscape-formatted file:
yt-dlp --cookies cookies.txt "URL"
8.3 .netrc and Credential Management
Store login credentials in a .netrc file for automated authentication without passing plaintext passwords on the command line.
Step 1: Create .netrc File & Set Permissions
Create ~/.netrc and restrict read/write access to the local user:
touch ${HOME}/.netrc
chmod a-rwx,u+rw ${HOME}/.netrc
Step 2: Configure Credential Entries
Add service account credentials using the lowercase extractor identifier:
machine youtube login myaccount@gmail.com password mypassword123
machine twitch login my_twitch_user password my_twitch_password
Step 3: Invoke Authentication
Activate .netrc lookup via --netrc or pass dynamic decryption commands using --netrc-cmd:
# Enable standard netrc credential lookup
yt-dlp --netrc "URL"
# Decrypt GPG-encrypted authinfo file on demand
yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' "URL"
9. Persistent Configuration Setup (yt-dlp.conf)
9.1 Configuration File Locations & Priority Order
Configuration options are evaluated on every yt-dlp run in the following priority order:
- Explicit Location: Paths supplied via
--config-locations PATH. - Portable Configuration:
yt-dlp.confin the executable binary directory. - Home Configuration:
yt-dlp.confinside the path supplied to-P, or the current directory. - User Configuration:
- Linux / macOS:
${XDG_CONFIG_HOME}/yt-dlp/config(typically~/.config/yt-dlp/config). - Windows:
%APPDATA%/yt-dlp/config(typicallyC:\Users\<User>\AppData\Roaming\yt-dlp\config).
- Linux / macOS:
- System Configuration:
/etc/yt-dlp.conf.
(To bypass configuration files for a specific execution, pass --ignore-config).
9.2 Syntax & Formatting Rules
- Place one command option per line.
- Do not leave leading whitespace before option switches.
- Lines beginning with
#are treated as comments. - File encoding can be declared on the first line via
# coding: utf-8.
Configuration Do's and Don'ts
# ==========================================
# VALID CONFIGURATION FILE
# ==========================================
# coding: utf-8
-o ~/Downloads/%(title)s.%(ext)s
--embed-metadata
--format-sort res:1080
# ==========================================
# INVALID CONFIGURATION FILE (DO NOT USE)
# ==========================================
-o ~/Downloads/%(title)s.%(ext)s # ERROR: Leading whitespace before flag
--proxy 127.0.0.1:1080 # WARNING: Unquoted strings containing spaces
9.3 Production Configuration Template
Save the following configuration as your user profile (e.g., ~/.config/yt-dlp/config) for standard archival downloading:
# coding: utf-8
# Production Configuration Template for yt-dlp
# Default output directory and filename template
-o ~/Downloads/%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s
# Prefer 1080p MP4/M4A streams with fallback to general formats
-f bv*[height<=1080][ext=mp4]+ba[ext=m4a]/b[height<=1080][ext=mp4]/bv*+ba/b
--merge-output-format mp4
# Embed metadata, thumbnails, and subtitles
--embed-metadata
--embed-thumbnail
--embed-subs
--sub-langs "en.*"
# Archive file location to skip duplicates
--download-archive ~/.config/yt-dlp/download_archive.txt
# Download speed and fragment optimization
--concurrent-fragments 4
10. Advanced Execution & Network Tuning
10.1 Section Trimming and Chapter Splitting
Slice specific time intervals or split videos into independent files based on embedded chapter markers.
# Download a precise timestamp section (1 minute to 5 minutes)
yt-dlp --download-sections "*00:01:00-00:05:00" "URL"
# Split video into separate files using chapter boundaries
yt-dlp --split-chapters -o "%(title)s - %(chapter_number)s %(chapter)s.%(ext)s" "URL"
# Omit chapters matching regex pattern from the download
yt-dlp --remove-chapters "sponsor" "URL"
10.2 Network Proxies and Client Impersonation
Bypass geo-restrictions, IP rate limits, and TLS fingerprinting using proxy routing and browser impersonation.
# Route traffic through an HTTP/HTTPS proxy
yt-dlp --proxy "http://username:password@proxy.example.com:8080" "URL"
# Route traffic through a SOCKS5 proxy
yt-dlp --proxy "socks5://127.0.0.1:1080" "URL"
# Impersonate browser TLS fingerprints using curl_cffi
yt-dlp --impersonate "chrome" "URL"
# Inject X-Forwarded-For headers to spoof client origin country
yt-dlp --xff "US" "URL"
Impersonation Dependency Note: The curl_cffi package is pre-bundled in most official release binaries except the Unix zipimport binary (yt-dlp) and 32-bit Windows binary (yt-dlp_x86.exe). If you are running the Unix zipimport binary, install curl_cffi via pip install "yt-dlp[default,curl-cffi]" to enable --impersonate.
10.3 Speed Optimization & Rate Limiting
Tune connection parallelism or limit bandwidth consumption.
# Download 8 DASH/HLS stream fragments concurrently
yt-dlp -N 8 "URL"
# Limit download rate to 2 Megabytes per second
yt-dlp -r 2M "URL"
# Set minimum bitrate threshold to trigger re-extraction if connection is throttled
yt-dlp --throttled-rate 100K "URL"
# Set request sleep intervals to avoid IP rate-limiting blocks
yt-dlp --sleep-requests 0.75 --sleep-interval 5 --max-sleep-interval 20 "URL"
11. Scenario-Based Command Cheat Sheet
11.1 Rapid Reference Table
Scenario / Goal | Complete Command Line |
1. Highest Quality Default |
|
2. Max 1080p MP4 + Subs + Metadata |
|
3. High Quality MP3 + Art + Tags |
|
4. Full Channel Backup (Archive Skip) |
|
5. Playlist Subset in Reverse |
|
6. Trim Precise Timestamp Segment |
|
7. Private Video (Chrome Cookies) |
|
8. SOCKS5 Proxy + Sponsor Block Cut |
|
9. Audio Batch List + Rate Limit |
|
10. Chapter Splitting into Subdirectories |
|
