Python 选项速查

Python API 通过传入 ydl_opts 字典来配置行为。以下是最常用的选项。

完整选项列表请参考 yt-dlp 源码 YoutubeDL.py 中 YoutubeDL.__init__ 的文档字符串。

基础用法

import yt_dlp

ydl_opts = {
    # ... 选项字典
}

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

格式与质量

Python Key	类型	说明	CLI 对应
`format`	`str`	格式选择字符串	`-f`
`format_sort`	`list[str]`	格式排序规则	`-S`
`merge_output_format`	`str`	合并输出格式	`--merge-output-format`

输出路径

Python Key	类型	说明	CLI 对应
`outtmpl`	`str`	输出文件名模板	`-o`
`paths`	`dict`	下载路径	`-P`
`overwrites`	`bool`	是否覆盖文件	`--force-overwrites`
`restrictfilenames`	`bool`	限制为 ASCII 文件名	`--restrict-filenames`
`windowsfilenames`	`bool`	Windows 兼容文件名	`--windows-filenames`

下载行为

Python Key	类型	说明	CLI 对应
`skip_download`	`bool`	不下载，只提取信息	`--skip-download`
`continuedl`	`bool`	断点续传	`-c`
`ratelimit`	`int`	限速（字节/秒）	`-r`
`retries`	`int`	重试次数	`-R`
`fragment_retries`	`int`	分段重试次数	`--fragment-retries`
`concurrent_fragment_downloads`	`int`	并发分段数	`-N`
`socket_timeout`	`int`	超时秒数	`--socket-timeout`
`noplaylist`	`bool`	禁止播放列表	`--no-playlist`
`playliststart`	`int`	播放列表起始	`--playlist-start`
`playlistend`	`int`	播放列表结束	`--playlist-end`
`playlist_items`	`str`	播放列表选择	`-I`
`download_archive`	`str`	归档文件路径	`--download-archive`

认证

Python Key	类型	说明	CLI 对应
`cookiefile`	`str`	Cookies 文件路径	`--cookies`
`cookiesfrombrowser`	`tuple`	浏览器 Cookies	`--cookies-from-browser`
`username`	`str`	用户名	`-u`
`password`	`str`	密码	`-p`

网络

Python Key	类型	说明	CLI 对应
`proxy`	`str`	代理地址	`--proxy`
`source_address`	`str`	绑定 IP	`--source-address`
`http_headers`	`dict`	自定义 HTTP 头	`--add-header`
`geo_bypass`	`bool`	地理限制绕过	`--geo-bypass`

字幕

Python Key	类型	说明	CLI 对应
`writesubtitles`	`bool`	下载字幕	`--write-sub`
`writeautomaticsub`	`bool`	下载自动字幕	`--write-auto-sub`
`subtitleslangs`	`list[str]`	字幕语言列表	`--sub-lang`
`subtitlesformat`	`str`	字幕格式	`--sub-format`

缩略图

Python Key	类型	说明	CLI 对应
`writethumbnail`	`bool`	下载缩略图	`--write-thumbnail`

输出控制

Python Key	类型	说明	CLI 对应
`quiet`	`bool`	静默模式	`-q`
`verbose`	`bool`	详细输出	`-v`
`no_warnings`	`bool`	隐藏警告	`--no-warnings`
`ignoreerrors`	`bool`	忽略错误	`-i`

后处理器

Python Key	类型	说明
`postprocessors`	`list[dict]`	后处理器列表
`postprocessor_args`	`dict`	后处理器额外参数
`keepvideo`	`bool`	保留原始文件

回调函数

Python Key	类型	说明
`progress_hooks`	`list[callable]`	进度回调函数列表
`postprocessor_hooks`	`list[callable]`	后处理回调函数

进度回调示例

def my_hook(d):
    if d['status'] == 'downloading':
        print(f"\r{d.get('_percent_str', '?')} at {d.get('_speed_str', '?')}", end='')
    elif d['status'] == 'finished':
        print(f"\n完成: {d['filename']}")
    elif d['status'] == 'error':
        print(f"\n错误: {d.get('filename', 'unknown')}")

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

信息提取

# 提取信息不下载
with yt_dlp.YoutubeDL({'skip_download': True}) as ydl:
    info = ydl.extract_info("URL", download=False)

# 扁平化提取（播放列表只获取目录）
with yt_dlp.YoutubeDL({'extract_flat': True}) as ydl:
    info = ydl.extract_info("PLAYLIST_URL", download=False)

# 使用 sanitize_info 获取可序列化的信息
info = yt_dlp.YoutubeDL.sanitize_info(info)

Python 选项速查

On this page