CLI 与 Python 对比

yt-dlp 提供两种使用方式，本页帮助你理解它们的差异，选择最适合的方式。

对照表

特性	CLI（命令行）	Python API
上手难度	⭐ 简单	⭐⭐ 中等
灵活性	中等	高
批量自动化	Shell 脚本	原生支持
错误处理	退出码	try/except
回调/钩子	不支持	支持
进度监控	终端输出	回调函数
集成到其他程序	子进程调用	直接导入
适用场景	手动下载、快速使用	程序集成、自动化工作流

同一功能的对比

基础下载

yt-dlp -f "bestvideo+bestaudio" -o "%(title)s.%(ext)s" "URL"

import yt_dlp

ydl_opts = {
    'format': 'bestvideo+bestaudio',
    'outtmpl': '%(title)s.%(ext)s',
}

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

提取音频

yt-dlp -x --audio-format m4a --audio-quality 0 \
  --embed-thumbnail --add-metadata "URL"

import yt_dlp

ydl_opts = {
    'format': 'bestaudio/best',
    'writethumbnail': True,
    'postprocessors': [
        {
            'key': 'FFmpegExtractAudio',
            'preferredcodec': 'm4a',
            'preferredquality': '0',
        },
        {'key': 'EmbedThumbnail'},
        {'key': 'FFmpegMetadata'},
    ],
}

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

CLI 选项到 Python 映射规则

大部分 CLI 选项可以直接映射到 Python 的 ydl_opts 字典：

CLI 选项	Python 参数	说明
`-f FORMAT`	`'format': 'FORMAT'`	格式选择
`-o TEMPLATE`	`'outtmpl': 'TEMPLATE'`	输出模板
`-x`	`postprocessors` 中添加 `FFmpegExtractAudio`	提取音频
`--audio-format m4a`	`'preferredcodec': 'm4a'`	音频格式
`--audio-quality 0`	`'preferredquality': '0'`	音频质量
`--embed-thumbnail`	`'writethumbnail': True` + `EmbedThumbnail` PP	嵌入封面
`--add-metadata`	`FFmpegMetadata` PP	写入元数据
`--proxy URL`	`'proxy': 'URL'`	代理设置
`--cookies FILE`	`'cookiefile': 'FILE'`	Cookies 文件
`--write-sub`	`'writesubtitles': True`	下载字幕
`--no-overwrites`	`'overwrites': False`	不覆盖文件

完整映射参考：CLI 的 --help 中每个选项对应的 Python key 可在 yt-dlp 源码 options.py 中找到 dest= 参数名。

Python 独有能力

进度回调

import yt_dlp

def progress_hook(d):
    if d['status'] == 'downloading':
        percent = d.get('_percent_str', 'N/A')
        speed = d.get('_speed_str', 'N/A')
        print(f"\r下载中: {percent} | 速度: {speed}", end='')
    elif d['status'] == 'finished':
        print(f"\n下载完成: {d['filename']}")

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

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

信息提取（不下载）

import yt_dlp

with yt_dlp.YoutubeDL({'skip_download': True}) as ydl:
    info = ydl.extract_info("URL", download=False)

    print(f"标题: {info['title']}")
    print(f"时长: {info['duration']}s")
    print(f"可用格式数: {len(info.get('formats', []))}")

    for f in info.get('formats', []):
        print(f"  {f['format_id']}: {f.get('ext')} "
              f"{f.get('resolution', 'audio')} "
              f"{f.get('filesize_approx', 0) / 1024 / 1024:.1f}MB")

错误处理

import yt_dlp

ydl_opts = {'format': 'bestaudio/best'}

try:
    with yt_dlp.YoutubeDL(ydl_opts) as ydl:
        ydl.download(["URL"])
except yt_dlp.utils.DownloadError as e:
    print(f"下载失败: {e}")
except yt_dlp.utils.ExtractorError as e:
    print(f"解析失败: {e}")
except Exception as e:
    print(f"未知错误: {e}")

如何选择？

一次性下载 → 用 CLI，快速方便
写脚本批量处理 → 用 Python，更灵活
集成到现有项目 → 用 Python，直接 import
需要进度回调 → 用 Python，支持 hooks
快速测试参数 → 用 CLI，验证后再写 Python 代码

CLI 与 Python 对比

On this page