yt-dlp 速查表

快速索引最常用的命令和 Python 配置，适合打印或收藏。

基础下载

用途	CLI 命令
默认下载	`yt-dlp "URL"`
指定保存路径	`yt-dlp -o "~/Downloads/%(title)s.%(ext)s" "URL"`
只看信息不下载	`yt-dlp --print filename -o "%(title)s.%(ext)s" "URL"`
列出可用格式	`yt-dlp -F "URL"`

视频下载

用途	CLI 命令
最佳画质	`yt-dlp -f "bv+ba" "URL"`
指定 mp4 格式	`yt-dlp -f "bv[ext=mp4]+ba[ext=m4a]" --merge-output-format mp4 "URL"`
限制 720p	`yt-dlp -f "bv[height<=720]+ba" "URL"`
限制 1080p	`yt-dlp -f "bv[height<=1080]+ba" "URL"`
格式排序	`yt-dlp -S "res:720,ext:mp4" "URL"`

音频下载

用途	CLI 命令
提取为 MP3	`yt-dlp -x --audio-format mp3 "URL"`
提取为 FLAC	`yt-dlp -x --audio-format flac "URL"`
最佳音质 MP3	`yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"`
只下载音频流	`yt-dlp -f "ba" "URL"`

字幕

用途	CLI 命令
列出字幕	`yt-dlp --list-subs "URL"`
下载中文字幕	`yt-dlp --write-sub --sub-lang zh-Hans "URL"`
嵌入字幕到视频	`yt-dlp --embed-subs "URL"`
下载自动生成字幕	`yt-dlp --write-auto-sub --sub-lang zh-Hans "URL"`

批量 & 播放列表

用途	CLI 命令
下载播放列表	`yt-dlp "PLAYLIST_URL"`
播放列表范围	`yt-dlp --playlist-items 1:5 "URL"`
从文件读取链接	`yt-dlp -a urls.txt`
跳过已下载	`yt-dlp --download-archive archive.txt "URL"`

认证 & 网络

用途	CLI 命令
使用 Cookies	`yt-dlp --cookies cookies.txt "URL"`
从浏览器导入	`yt-dlp --cookies-from-browser chrome "URL"`
使用代理	`yt-dlp --proxy "http://127.0.0.1:7890" "URL"`
并发下载	`yt-dlp -N 4 "URL"`
限速	`yt-dlp -r 5M "URL"`

平台专用

Bilibili

# 视频
yt-dlp --cookies-from-browser chrome "https://www.bilibili.com/video/BV..."

# 指定画质
yt-dlp --cookies-from-browser chrome -f "bv+ba" "https://www.bilibili.com/video/BV..."

YouTube

# 最佳 mp4
yt-dlp -f "bv[ext=mp4]+ba[ext=m4a]" --merge-output-format mp4 "https://youtu.be/..."

# 嵌入缩略图 + 字幕
yt-dlp --embed-thumbnail --embed-subs "https://youtu.be/..."

Python API 速查

基础下载

import yt_dlp

with yt_dlp.YoutubeDL() as ydl:
    ydl.download(["URL"])

常用配置模板

# 下载最佳 mp4
opts = {
    'format': 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]',
    'merge_output_format': 'mp4',
    'outtmpl': '%(title)s.%(ext)s',
}

# 提取 mp3
opts = {
    'format': 'bestaudio/best',
    'postprocessors': [{
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'mp3',
        'preferredquality': '320',
    }],
}

# 只获取信息
opts = {
    'quiet': True,
    'no_warnings': True,
}
with yt_dlp.YoutubeDL(opts) as ydl:
    info = ydl.extract_info("URL", download=False)

进度回调

def progress_hook(d):
    if d['status'] == 'downloading':
        print(f"下载中: {d.get('_percent_str', 'N/A')}")
    elif d['status'] == 'finished':
        print("下载完成，后处理中...")

opts = {
    'progress_hooks': [progress_hook],
}

信息提取字段

info = ydl.extract_info("URL", download=False)
info['title']       # 标题
info['duration']    # 时长（秒）
info['upload_date'] # 上传日期 YYYYMMDD
info['uploader']    # 上传者
info['view_count']  # 播放量
info['formats']     # 所有可用格式列表
info['thumbnail']   # 缩略图 URL
info['description'] # 描述

输出模板常用变量

变量	说明	示例
`%(title)s`	视频标题	`My Video`
`%(id)s`	视频 ID	`dQw4w9WgXcQ`
`%(ext)s`	扩展名	`mp4`
`%(uploader)s`	上传者	`Rick Astley`
`%(upload_date>%Y-%m-%d)s`	格式化日期	`2023-01-15`
`%(resolution)s`	分辨率	`1920x1080`
`%(playlist_index)s`	播放列表序号	`01`

完整选项参考请查看 CLI 选项参考和 Python 选项参考。

yt-dlp 速查表

On this page