yt-dlp 是一个功能丰富的命令行音频/视频下载器，基于 youtube-dl 分支开发，支持数千个网站，具有格式排序、SponsorBlock 集成、多线程下载等强大特性。
$ yt-dlp "https://www.youtube.com/watch?v=..."
# 下载最佳画质+最佳音质并自动合并
$ yt-dlp -f "bv+ba/b" URL
# 仅提取音频为 mp3
$ yt-dlp -x --audio-format mp3 URL
# 下载整个播放列表
$ yt-dlp -o "%(playlist)s/%(title)s.%(ext)s" URL
并行下载 HLS/DASH 片段，使用 -N 设置线程数，大幅提升下载速度。
使用 -S 精确控制格式偏好——分辨率、编解码器、比特率、文件大小等。
自动标记或移除 YouTube 视频中的赞助商片段、片头片尾等内容。
通过提取器和后处理器插件扩展功能，支持自定义开发和社区共享。
$ yt-dlp -U
# 切换到 nightly 渠道
$ yt-dlp --update-to nightly
提供三个发布渠道：stable（稳定版）、nightly（每日构建，推荐普通用户）和 master（最新代码）。
yt-dlp [OPTIONS] [--] URL [URL...]
下载最佳质量视频
提取音频为 MP3
限制分辨率不超过 720p
查看可用格式列表
下载播放列表，每个视频存入单独文件夹
使用代理 + 8 线程并行下载片段
从浏览器获取 Cookie
下载时间范围片段（需要 ffmpeg）
点击展开各分类查看完整选项说明。
-h, --help打印帮助文本并退出--version打印程序版本并退出-U, --update更新到最新版本--update-to [CHANNEL]@[TAG]升级/降级到特定版本-i, --ignore-errors忽略下载和后处理错误--abort-on-error发生错误时中止下载--flat-playlist不提取播放列表的视频详情--live-from-start从开始下载直播流（实验性）--wait-for-video MIN[-MAX]等待计划的直播变得可用--mark-watched标记视频为已观看--compat-options OPTSyoutube-dl 兼容性选项--proxy URL使用 HTTP/HTTPS/SOCKS 代理--socket-timeout SECONDS连接超时时间--source-address IP绑定客户端 IP 地址--impersonate CLIENT[:OS]模拟浏览器请求-4, --force-ipv4强制使用 IPv4-6, --force-ipv6强制使用 IPv6--geo-verification-proxy URL地理限制验证代理--xff VALUE伪造 X-Forwarded-For 标头-I, --playlist-items ITEM_SPEC选择播放列表中的特定项目--min-filesize SIZE最小文件大小限制--max-filesize SIZE最大文件大小限制--date DATE仅下载指定日期上传的视频--match-filters FILTER通用视频过滤器--no-playlist仅下载视频，不下载播放列表--download-archive FILE跳过已下载过的视频--max-downloads NUMBER最大下载数量--age-limit YEARS年龄限制过滤-N, --concurrent-fragments N并发下载片段数（默认 1）-r, --limit-rate RATE最大下载速率，如 50K 或 4.2M-R, --retries RETRIES重试次数（默认 10）--download-sections REGEX按时间范围或章节下载--downloader NAME使用外部下载器（aria2c, curl 等）--hls-use-mpegtsHLS 使用 mpegts 容器--playlist-random随机顺序下载播放列表-o, --output TEMPLATE输出文件名模板-P, --paths [TYPES:]PATH下载路径--restrict-filenames限制为 ASCII 文件名-w, --no-overwrites不覆盖已有文件-c, --continue恢复部分下载--write-info-json写入视频元数据 JSON--cookies FILE使用 Cookie 文件--cookies-from-browser BROWSER从浏览器自动提取 Cookie-a, --batch-file FILE从文件批量读取 URL-f, --format FORMAT视频格式代码-S, --format-sort SORTORDER格式排序字段-F, --list-formats列出可用格式--merge-output-format FORMAT合并时使用的容器格式--video-multistreams允许多视频流合并--audio-multistreams允许多音频流合并--prefer-free-formats优先选择免费容器--write-subs写入字幕文件--write-auto-subs写入自动生成的字幕--list-subs列出可用字幕--sub-format FORMAT字幕格式（srt / ass / vtt）--sub-langs LANGS下载指定语言的字幕-x, --extract-audio转换为仅音频文件--audio-format FORMAT音频格式（mp3, aac, flac 等）--audio-quality QUALITY音频质量 0（最佳）到 10--remux-video FORMAT重新封装视频容器--embed-subs嵌入字幕--embed-thumbnail嵌入缩略图作为封面--embed-metadata嵌入元数据到文件--split-chapters按章节拆分视频--exec CMD下载后执行命令--convert-subs FORMAT转换字幕格式--sponsorblock-mark CATS标记 SponsorBlock 章节--sponsorblock-remove CATS移除赞助商片段-u, --username USERNAME帐户用户名-p, --password PASSWORD帐户密码-2, --twofactor CODE双因素验证代码-n, --netrc使用 .netrc 身份验证--video-password PASSWORD视频密码yt-dlp 可以通过配置文件预设常用选项。配置文件按以下优先级顺序加载：
--config-locations 指定的文件yt-dlp.conf-P 指定路径中的 yt-dlp.conf# 以 # 开头的行是注释
# 始终提取音频
-x
# 使用代理
--proxy
127.0.0.1:3128# 保存到 YouTube 目录
-o
~/YouTube/%(title)s.%(ext)s# 嵌入缩略图和元数据
--embed-thumbnail
--embed-metadata
⚠ 注意
配置文件中的选项与命令行完全相同。在 - 或 -- 后不能有空格。使用 --ignore-config 禁用所有配置文件。
使用 -o 选项自定义输出文件名。模板使用 %(字段名)s 语法引用视频元数据。当前默认模板是 %(title)s [%(id)s].%(ext)s。
按播放列表分目录
按上传年份分目录
频道/播放列表层级结构
高级：日期格式化 + 算术 + 默认值
💡 提示
使用 yt-dlp -j URL 查看特定视频的所有可用字段。支持对象遍历（%(tags.0)s）、算术运算（%(playlist_index+10)03d）和日期格式化（%(upload_date>%Y-%m-%d)s）。
默认情况下，yt-dlp 下载最佳可用质量（-f bv*+ba/b）。使用 -f 精确选择格式，使用 -S 自定义排序规则。
# 下载最佳 mp4，回退到最佳可用
-f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"
# 分辨率最大但不超过 720p
-S "height:720"
# 下载最小文件
-S "+size,+br"
# 文件大小最接近 50MB
-f b -S "filesize~50M"
yt-dlp 支持通过外部文件加载提取器插件和后处理器插件。插件从 yt_dlp_plugins 命名空间包中加载。
⚠ 安全警告
所有插件都会被导入，不会对插件代码进行安全检查。请仅使用您信任的插件！
# Windows 用户插件（推荐）
%APPDATA%\yt-dlp\plugins\<包名>\yt_dlp_plugins\
# Linux/macOS 用户插件（推荐）
~/.config/yt-dlp/plugins/<包名>/yt_dlp_plugins/
yt_dlp_plugins/
├── extractor/
│ └── myplugin.py
└── postprocessor/
└── myplugin.py
--use-postprocessor NAME 调用yt-dlp --verbose 验证插件是否加载yt-dlp 可以作为 Python 库直接嵌入到你的应用程序中，提供比命令行更灵活的控制方式。
from yt_dlp import YoutubeDL
URLS = ['https://...']
with YoutubeDL() as ydl:
ydl.download(URLS)
ydl_opts = {
'format': 'm4a/bestaudio/best',
'postprocessors': [{
'key': 'FFmpegExtractAudio',
'preferredcodec': 'm4a',
}]
}
with YoutubeDL(ydl_opts) as ydl:
ydl.download(URLS)
import json, yt_dlp
with yt_dlp.YoutubeDL() as ydl:
info = ydl.extract_info(URL,
download=False)
print(json.dumps(
ydl.sanitize_info(info)))
def longer_than_a_minute(info, *,
incomplete):
duration = info.get('duration')
if duration and duration < 60:
return 'Video too short'
ydl_opts = {
'match_filter':
longer_than_a_minute,
}