| name | video-download |
| description | Download videos, playlists, subtitles, thumbnails, chapters, and metadata with yt-dlp. Use when the user asks to save online video/audio locally, archive a playlist/channel, extract audio, fetch subtitles/transcripts, troubleshoot yt-dlp 403/signature/cookie/plugin issues, configure yt-dlp defaults, or use yt-dlp plugins such as PO token providers, Return YouTube Dislikes, DeArrow, ChromeCookieUnlock, or sample extractor/postprocessor plugins. |
Video Download
Use yt-dlp as the default downloader for video/audio archival tasks. Optimize for
repeatability: explicit output paths, dry-run metadata checks, archive files for batches,
and verification after the download.
Procedure
-
Confirm the user has rights to download the content. Do not help bypass DRM, paywalls,
account bans, or access controls. For private or age-restricted content, prefer normal
authenticated access via cookies from the user's browser.
-
Identify the job shape: single URL vs playlist/channel, video vs audio-only, required
quality/container, subtitle languages, metadata/thumbnail needs, and destination folder.
-
Check tools before running:
yt-dlp --version
ffmpeg -version
yt-dlp --verbose --simulate "URL"
If yt-dlp is missing, install or update with the environment's Python tool. In this
repo default to uv tool install yt-dlp or uv tool upgrade yt-dlp; otherwise use the
official binary or python -m pip install -U "yt-dlp[default]" only when that matches
the user's environment.
-
Inspect before downloading:
yt-dlp -F "URL"
yt-dlp --dump-single-json --simulate "URL" > info.json
yt-dlp --print "%(title)s [%(id)s] %(duration_string)s %(webpage_url)s" "URL"
-
Download with an explicit template. For general video:
yt-dlp \
-P "./downloads" \
-o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title).180B [%(id)s].%(ext)s" \
-f "bv*[height<=1080]+ba/best[height<=1080]/best" \
--merge-output-format mkv \
--embed-metadata --embed-thumbnail --embed-chapters \
--write-subs --write-auto-subs --sub-langs "en.*,ko.*" --sub-format "srt/best" \
--download-archive "./downloads/.yt-dlp-archive.txt" \
"URL"
For audio-only:
yt-dlp -P "./downloads/audio" -x --audio-format m4a --audio-quality 0 \
--embed-metadata --embed-thumbnail \
-o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title).180B [%(id)s].%(ext)s" \
"URL"
-
Verify outputs: file exists, playable container, expected subtitles/metadata, and
archive entry written for batch jobs. Use ffprobe when available.
Configuration
Put persistent defaults in the native config location, not in ad hoc shell aliases:
- Linux/macOS:
${XDG_CONFIG_HOME}/yt-dlp/config or ~/.config/yt-dlp/config
- Windows:
%APPDATA%\yt-dlp\config
Starter config:
-o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title).180B [%(id)s].%(ext)s"
-f "bv*[height<=1080]+ba/best[height<=1080]/best"
--merge-output-format mkv
--embed-metadata
--embed-thumbnail
--embed-chapters
--write-subs
--write-auto-subs
--sub-langs "en.*,ko.*"
--sub-format "srt/best"
--download-archive ".yt-dlp-archive.txt"
Use --ignore-config for one-off clean runs and --config-locations PATH when testing a
new config file.
Plugins
Treat plugins as executable code. Install only from trusted repositories, pin or record the
source when possible, and run yt-dlp --verbose after installation to confirm loaded
plugins. The official plugin shape is:
yt_dlp_plugins/
extractor/
myplugin.py
postprocessor/
myplugin.py
Recommended user plugin directories:
- Linux/macOS:
${XDG_CONFIG_HOME}/yt-dlp/plugins/<package>/yt_dlp_plugins/
- Windows:
%APPDATA%\yt-dlp\plugins\<package>\yt_dlp_plugins\
Useful plugin-related options:
yt-dlp --plugin-dirs "/path/to/plugins" --verbose "URL"
yt-dlp --no-plugin-dirs --verbose "URL"
YTDLP_NO_PLUGINS=1 yt-dlp --verbose "URL"
Known advanced plugins to consider, after checking their current README/issues:
- YouTube PO Token Framework/providers: use for YouTube 403/signature/player-client
failures. Pair with
--extractor-args "youtube:player_client=web,android,ios" only when
the current provider docs recommend it.
- YouTube Agegate Bypass: use only for content the user is legally allowed and eligible to
access; prefer authenticated cookies first.
- Return YouTube Dislikes: metadata enrichment.
- DeArrow: community title/thumbnail post-processing.
- ChromeCookieUnlock: unlock Chromium cookie DBs for
--cookies-from-browser chrome or
edge when normal browser cookie extraction fails.
Do not blindly paste stale plugin install commands. Verify names and install instructions
from the plugin repository immediately before installing.
Troubleshooting
- Run with
--verbose and inspect yt-dlp, ffmpeg, Python, extractor, cookie, and plugin
lines before changing flags.
- Update first for extractor breakage:
yt-dlp -U for official binaries, or reinstall the
package for pip/uv installs. For persistent YouTube breakage, consider the official
nightly channel.
- Use
--cookies-from-browser chrome|edge|firefox for content that requires login. Never
print or commit cookies.
- Use
--list-subs, --list-thumbnails, and -F to understand availability before
assuming a site exposes a format.
- For playlists/channels, use
--download-archive, --max-downloads, and explicit playlist
ranges to avoid accidental massive downloads.
Sources
