mcpField
Y
yt-dlp

yt-dlp

官方精选
github.com媒体工具203.0kyt-dlp1 天前更新
代码仓库访问官网

关于 yt-dlp

yt-dlp 是一个命令行工具，可从多种在线来源下载视频和音频内容。它支持广泛的平台和格式，适合本地保存媒体。

主要功能

  1. 01用单条命令从支持的网站下载视频
  2. 02提取音频并转换为 MP3 等格式
  3. 03批量处理多个 URL

适用场景

  1. 01存档视频内容供离线查看
  2. 02将在线视频转换为音频文件用于音乐或播客
  3. 03构建自动化工作流来下载和处理媒体

安装

选择你的系统或包管理器，复制命令到终端运行。

$
brew install yt-dlp

安装完成后运行yt-dlp --version确认安装成功。

命令示例

常用命令按使用顺序排列。

01
yt-dlp https://example.com/video
02
yt-dlp -x --audio-format mp3 URL

详细介绍

YT-DLP

发布版本 Python 版本 PyPI Discord 许可证：Unlicense 提交

yt-dlp 是一款功能丰富的命令行音视频下载器，支持数千个站点。该项目是基于已停止维护的 youtube-dlc 对 youtube-dl 所做的分支。

安装

Windows Unix MacOS PyPI Source Tarball Other variants All versions

你可以通过二进制文件、pip或第三方包管理器安装 yt-dlp。详细说明请参阅维基。

发布文件

推荐
文件说明
yt-dlp跨平台的 zipimport 二进制文件。需要 Python（Linux/BSD 推荐）
yt-dlp.exeWindows（Win10+）独立 x64 二进制文件（Windows 推荐）
yt-dlp_macos通用 MacOS（10.15+）独立可执行文件（MacOS 推荐）
替代项
文件说明
yt-dlp_linuxLinux（glibc 2.17+）独立 x86_64 二进制文件
yt-dlp_linux.zip未打包的 Linux（glibc 2.17+）x86_64 可执行文件（不自动更新）
yt-dlp_linux_aarch64Linux（glibc 2.17+）独立 aarch64 二进制文件
yt-dlp_linux_aarch64.zip未打包的 Linux（glibc 2.17+）aarch64 可执行文件（不自动更新）
yt-dlp_linux_armv7l.zip未打包的 Linux（glibc 2.31+）armv7l 可执行文件（不自动更新）
yt-dlp_musllinuxLinux（musl 1.2+）独立 x86_64 二进制文件
yt-dlp_musllinux.zip未打包的 Linux（musl 1.2+）x86_64 可执行文件（不自动更新）
yt-dlp_musllinux_aarch64Linux（musl 1.2+）独立 aarch64 二进制文件
yt-dlp_musllinux_aarch64.zip未打包的 Linux（musl 1.2+）aarch64 可执行文件（不自动更新）
yt-dlp_x86.exeWindows（Win10+）独立 x86（32 位）二进制文件
yt-dlp_win_x86.zip未打包的 Windows（Win10+）x86（32 位）可执行文件（不自动更新）
yt-dlp_arm64.exeWindows（Win10+）独立 ARM64 二进制文件
yt-dlp_win_arm64.zip未打包的 Windows（Win10+）ARM64 可执行文件（不自动更新）
yt-dlp_win.zip未打包的 Windows（Win10+）x64 可执行文件（不自动更新）
yt-dlp_macos.zip未打包的 MacOS（10.15+）可执行文件（不自动更新）
杂项
文件说明
yt-dlp.tar.gz源代码 tarball
SHA2-512SUMSGNU 风格的 SHA512 校验和
SHA2-512SUMS.sigSHA512 校验和的 GPG 签名文件
SHA2-256SUMSGNU 风格的 SHA256 校验和
SHA2-256SUMS.sigSHA256 校验和的 GPG 签名文件

用于验证 GPG 签名的公钥可在此处获取 用法示例：

curl -L https://github.com/yt-dlp/yt-dlp/raw/master/public.key | gpg --import
gpg --verify SHA2-256SUMS.sig SHA2-256SUMS
gpg --verify SHA2-512SUMS.sig SHA2-512SUMS
许可证

虽然 yt-dlp 采用 Unlicense 许可，但许多发布文件包含来自其他项目的代码，这些代码使用不同的许可证。

其中最值得注意的是，PyInstaller 打包的可执行文件包含 GPLv3+ 许可的代码，因此合并后的作品采用 GPLv3+ 许可。

zipimport 形式的 Unix 可执行文件（yt-dlp）和发布压缩包（yt-dlp.tar.gz）包含来自 meriyah 的 ISC 许可代码，以及来自 astring 的 MIT 许可代码。

更多详情请参阅 THIRD_PARTY_LICENSES.txt。

Git 仓库、PyPI 源码分发包和 PyPI 构建分发包（wheel）仅包含采用 Unlicense 许可的代码。

注意：手册页、命令行自动补全文件等可在源码压缩包中获取。

更新

如果使用的是发布二进制文件，可以使用 yt-dlp -U 进行更新

如果通过 pip 安装，只需重新运行用于安装程序的同一条命令

对于其他第三方包管理器，请参阅维基或查看其文档

目前有三个二进制文件发布渠道：stable、nightly 和 master。

  • stable 是默认渠道，按照（基本上）每月一次的计划发布版本。虽然它被称为 stable，是因为其中许多更改都经过了 nightly 或 master 发布渠道用户的测试，但最新的 stable 版本往往已经“过时”，容易受到外部变化的影响（例如，网站更改其设置，导致 yt-dlp 无法正常工作）。
  • nightly 渠道会在代码库有更改的任何一天，于 UTC 午夜前不久发布版本。该渠道是项目开发情况的快照，也是 yt-dlp 普通用户的推荐渠道。nightly 版本可从 yt-dlp/yt-dlp-nightly-builds 获取，也可通过 yt-dlp PyPI 包的开发版获取（可使用 pip 的 --pre 标志安装）。
  • master 渠道会在每次推送到 master 分支后发布“金丝雀”版本。该渠道始终提供最新的修复和功能，但可能存在错误或回归问题。master 版本可从 yt-dlp/yt-dlp-master-builds 获取。

使用 --update/-U 时，发布二进制文件只会更新到当前渠道。 有较新版本可用时，可以使用 --update-to CHANNEL 切换到其他渠道。也可以使用 --update-to [CHANNEL@]TAG 升级或降级到某个渠道的指定标签。

你也可以使用 --update-to <repository>（<owner>/<repository>）更新到完全不同仓库中的渠道。不过，请谨慎选择要更新到的仓库；对于来自其他仓库的二进制文件，不会进行任何验证。

用法示例：

  • yt-dlp --update-to master 切换到 master 渠道并更新到其最新版本
  • yt-dlp --update-to [email protected] 升级或降级到 stable 渠道的 2023.07.06 标签版本
  • yt-dlp --update-to 2023.10.07 如果当前渠道存在 2023.10.07 标签，则升级或降级到该标签版本
  • yt-dlp --update-to example/[email protected] 升级或降级到 example/yt-dlp 仓库中标签为 2023.09.24 的版本

重要：使用 stable 版本时遇到问题的用户，应在提交错误报告前安装或更新到 nightly 版本：

# To update to nightly from stable executable/binary:
yt-dlp --update-to nightly

# To install nightly with pip:
python -m pip install -U --pre "yt-dlp[default]"

运行的 yt-dlp 版本若超过 90 天未更新，你将看到一条建议更新到最新版本的警告消息。 你可以在命令或配置文件中添加 --no-update 来屏蔽此警告。

依赖项

支持 Python 3.11 及以上版本（CPython 和 PyPy）。其他版本和实现可能无法正常工作。

虽然其他依赖项均为可选依赖，但强烈建议安装 ffmpeg、ffprobe、yt-dlp-ejs 以及受支持的 JavaScript 运行时/引擎

强烈推荐
网络
模拟

以下组件提供模拟浏览器请求的支持。某些采用 TLS 指纹识别的网站可能需要它们。

  • curl_cffi（推荐）- curl-impersonate 的 Python 绑定。为 Chrome、Edge 和 Safari 提供模拟目标。采用 MIT 许可证
    • 可以通过 curl-cffi 扩展项安装，例如 pip install "yt-dlp[default,curl-cffi]"
    • 目前包含在大多数构建版本中，但不包括 yt-dlp（Unix zipimport 二进制文件）和 yt-dlp_x86（Windows 32 位）
元数据
  • mutagen* - 用于在某些格式中配合 --embed-thumbnail 使用。采用 GPLv2+ 许可证
  • AtomicParsley - 当 mutagen/ffmpeg 无法处理时，用于在 mp4/m4a 文件中配合 --embed-thumbnail 使用。采用 GPLv2+ 许可证
  • xattr、pyxattr 或 setfattr - 用于在 Mac 和 BSD 上写入 xattr 元数据（--xattrs）。分别采用 MIT、LGPL2.1 和 GPLv2+ 许可证
杂项
  • pycryptodomex* - 用于解密 AES-128 HLS 流及各种其他数据。基于 BSD-2-Clause 许可
  • phantomjs - 用于需要运行 JavaScript 的部分提取器。现已不再用于 YouTube。近期将弃用。基于 BSD-3-Clause 许可
  • secretstorage* - 在 Linux 上解密基于 Chromium 的浏览器的 Cookie 时，供 --cookies-from-browser 访问 Gnome 密钥环。基于 BSD-3-Clause 许可
  • 你想与 --downloader 配合使用的任何外部下载器
已弃用
  • rtmpdump - 用于下载 rtmp 流。也可以改用 ffmpeg，并指定 --downloader ffmpeg。基于 GPLv2+ 许可

要使用或重新分发这些依赖项，必须同意各自的许可条款。

独立版发行二进制文件使用 Python 解释器构建，并包含标有 * 的软件包。

如果你缺少所尝试任务所需的依赖项，yt-dlp 会发出警告。所有当前可用的依赖项都会显示在 --verbose 输出的顶部。

编译

PyInstaller 独立版构建

要构建独立可执行文件，你必须安装 Python 和 pyinstaller（以及 yt-dlp 的任何可选依赖项，如有需要）。生成的可执行文件将适用于所用 Python 的 CPU 架构。

你可以运行以下命令：

python devscripts/install_deps.py --include-group pyinstaller
python devscripts/make_lazy_extractors.py
python -m bundle.pyinstaller

在某些系统上，你可能需要使用 py 或 python3，而不是 python。

python -m bundle.pyinstaller 可接受任何能够传递给 pyinstaller 的参数，例如 --onefile/-F 或 --onedir/-D，详细说明见此处。

注意：低于 4.4 的 PyInstaller 版本不支持在未使用虚拟环境的情况下安装来自 Windows 应用商店的 Python。

重要：不支持直接运行 pyinstaller，而不使用 python -m bundle.pyinstaller。这样做可能正常，也可能无法正常运行。

跨平台二进制文件（UNIX）

你需要构建工具 python（3.11+）、zip、make（GNU）、pandoc* 和 pytest*。

安装这些工具后，只需运行 make。

你也可以运行 make yt-dlp，仅编译二进制文件，而不更新任何其他文件。（此时不需要标有 * 的构建工具）

相关脚本
  • devscripts/install_deps.py - 安装 yt-dlp 的依赖项。
  • devscripts/update-version.py - 根据当前日期更新版本号。
  • devscripts/set-variant.py - 设置可执行文件的构建变体。
  • devscripts/make_changelog.py - 使用简短的提交消息创建 Markdown 更新日志，并更新 CONTRIBUTORS 文件。
  • devscripts/make_lazy_extractors.py - 创建延迟加载的提取器。在构建二进制文件（任何变体）前运行此脚本可提升启动性能。将环境变量 YTDLP_NO_LAZY_EXTRACTORS 设为非空值，可强制禁用提取器的延迟加载。

注意：更多信息请参阅它们的 --help。

派生项目

如果你在 GitHub 上派生了此项目，可以运行派生项目的构建工作流，自动将选定版本构建为构件。或者，你可以运行发布工作流，或启用夜间工作流来创建完整的（预）发布版本。

用法与选项

yt-dlp [OPTIONS] [--] URL [URL...]

提示：使用 CTRL+F（或 Command+F）按关键词搜索

通用选项：

-h, --help                      打印此帮助文本并退出
--version                       打印程序版本并退出
-U, --update                    将此程序更新到最新版本
--no-update                     不检查更新（默认）
--update-to [CHANNEL]@[TAG]     升级或降级到指定版本。
                                CHANNEL 也可以是代码仓库。若省略 CHANNEL
                                和 TAG，则分别默认为 "stable" 和 "latest"，
                                详见 "UPDATE"。支持的渠道：stable、
                                nightly、master
-i, --ignore-errors             忽略下载和后处理错误。
                                即使后处理失败，下载也视为成功
--no-abort-on-error             下载出错时继续处理下一个视频，
                                例如跳过播放列表中不可用的视频（默认）
--abort-on-error                出现错误时中止后续视频的下载（别名：--no-ignore-errors）
--list-extractors               列出所有受支持的提取器并退出
--extractor-descriptions        输出所有受支持提取器的说明并退出
--use-extractors NAMES          要使用的提取器名称，以逗号分隔。
                                也可以使用正则表达式、"all"、"default"
                                和 "end"（结束 URL 匹配），例如 --ies
                                "holodex.*,end,youtube"。在名称前加 "-" 可将其排除，例如 --ies
                                default,-generic。使用 --list-extractors 查看提取器名称列表。（别名：--ies）
--default-search PREFIX         对未限定的 URL 使用此前缀。例如
                                "gvsearch2:python" 会从 google videos 搜索 "python"
                                并下载两个视频。
                                使用 "auto" 让 yt-dlp 自行判断（"auto_warning" 会在猜测时输出警告）。
                                "error" 则直接抛出错误。默认值 "fixup_error" 会修复损坏的
                                URL，但若无法修复，会输出错误而不是进行搜索
--ignore-config                 不再加载任何配置文件，
                                但 --config-locations 指定的除外。
                                出于向后兼容，若系统配置文件中包含此选项，则不加载用户配置。
                                （别名：--no-config）
--no-config-locations           不加载任何自定义配置文件（默认）。
                                在配置文件中使用时，忽略当前文件中此前定义的所有 --config-locations
--config-locations PATH         主配置文件的位置；
                                可以是配置文件路径或其所在目录（"-" 表示标准输入）。可多次使用，
                                也可在其他配置文件中使用
--plugin-dirs DIR               额外的插件搜索目录路径。可多次使用以添加多个目录。
                                使用 "default" 搜索默认插件目录（默认）
--no-plugin-dirs                清除插件搜索目录，
                                包括默认目录以及之前通过 --plugin-dirs 指定的目录
--js-runtimes RUNTIME[:PATH]    额外启用的 JavaScript 运行时，
                                可选择指定运行时位置（可以是可执行文件路径或其所在目录）。可多次使用
                                以启用多个运行时。支持的运行时按优先级从高到低排列：deno、
                                node、quickjs、bun。默认仅启用 "deno"。将使用已启用且可用的
                                优先级最高的运行时。若要在 "deno" 可用时使用优先级较低的
                                运行时，需先传入 --no-js-
                                runtimes，再启用其他运行时
--no-js-runtimes                清除要启用的 JavaScript 运行时，
                                包括默认运行时以及之前通过 --js-runtimes 指定的运行时
--remote-components COMPONENT   允许 yt-dlp 在需要时获取的远程组件。若你使用官方可执行文件，
                                或已安装所需版本的 yt-dlp-ejs 包，则目前无需此选项。可多次使用
                                以允许多个组件。支持的值：
                                ejs:npm（来自 npm 的外部 JavaScript 组件）、ejs:github（来自 yt-dlp-ejs GitHub 的外部 JavaScript
                                组件）。默认不允许任何远程组件
--no-remote-components          禁止获取所有远程组件，
                                包括之前通过 --remote-components 或默认设置允许的组件。
--flat-playlist                 不展开播放列表中的 URL 结果条目；部分条目元数据可能缺失，
                                且可能跳过下载
--no-flat-playlist              完整提取播放列表中的视频（默认）
--live-from-start               从头下载直播。
                                目前为实验性功能，仅支持 YouTube、Twitch、TVer 和 mellow-fan
--no-live-from-start            从当前时间开始下载直播（默认）
--wait-for-video MIN[-MAX]      等待预定直播变为可用。传入重试之间等待的
                                最短秒数（或秒数范围）
--no-wait-for-video             不等待预定直播（默认）
--mark-watched                  将视频标记为已观看（即使使用 --simulate）
--no-mark-watched               不标记视频为已观看（默认）
--color [STREAM:]POLICY         是否在输出中使用颜色代码，可选择以 STREAM（stdout 或
                                stderr）作为前缀，以将设置应用于该流。可选值为 "always"、"auto"（默认）、"never" 或
                                "no_color"（使用不支持颜色的终端控制序列）。使用 "auto-tty" 或 "no_color-tty"
                                可仅根据终端支持情况决定。可多次使用
--compat-options OPTS           撤销 yt-dlp 对默认行为所做的部分更改，
                                以帮助保持与 youtube-dl 或 youtube-dlc
                                配置的兼容性。详见 "Differences in
                                default behavior"
--alias ALIASES OPTIONS         为选项字符串创建别名。除非别名以短横线 "-" 开头，否则会自动加上
                                "--" 前缀。参数按照 Python 字符串格式化
                                迷你语言进行解析。例如 --alias get-audio,-X "-S
                                aext:{0},abr -x --audio-format {0}" 会创建
                                接受一个参数（ARG0）的选项 "--get-audio" 和 "-X"，并展开为 "-S
                                aext:ARG0,abr -x --audio-format ARG0"。所有已定义的别名都会列在
                                --help 输出中。别名选项可以触发更多别名，因此请注意避免定义
                                递归选项。作为安全措施，每个别名最多可被触发 100
                                次。此选项可多次使用
-t, --preset-alias PRESET       应用一组预定义选项，例如
                                --preset-alias mp3。可用预设有：mp3、aac、mp4、mkv、sleep。
                                更多信息见末尾的 "Preset Aliases" 部分。此选项可多次使用

网络选项：

--proxy URL                     使用指定的 HTTP/HTTPS/SOCKS 代理。要
                                启用 SOCKS 代理，请指定正确的协议，
                                例如 socks5://user:[email protected]:1080/。
                                传入空字符串（--proxy ""）以直接连接
--socket-timeout SECONDS        放弃等待前的超时时间，单位为秒
--source-address IP             绑定的客户端 IP 地址
--impersonate CLIENT[:OS]       请求时模拟的客户端。例如 chrome、
                                chrome-110、chrome:windows-10。传入
                                --impersonate="" 可模拟任意客户端。
                                注意，对所有请求强制模拟可能会对下载
                                速度和稳定性产生不利影响
--list-impersonate-targets      列出可模拟的客户端
-4, --force-ipv4                所有连接都通过 IPv4 进行
-6, --force-ipv6                所有连接都通过 IPv6 进行
--enable-file-urls              启用 file:// URL。出于安全考虑，该功能默认禁用

地理限制：

--geo-verification-proxy URL    对于某些地理限制站点，使用此代理验证
                                IP 地址。实际下载仍使用 --proxy 指定的
                                默认代理（若未指定该选项，则不使用代理）
--xff VALUE                     伪造 X-Forwarded-For HTTP 头以尝试绕过
                                地理限制的方式。可选值为："default"
                                （仅在已知有效时使用）、"never"、CIDR
                                表示法的 IP 段，或两位 ISO 3166-2 国家
                                代码

视频选择：

-I, --playlist-items ITEM_SPEC  要下载的条目的播放列表索引，以逗号分隔。
                                可使用 "[START]:[STOP][:STEP]" 指定范围。
                                为向后兼容，也支持 START-STOP 格式。
                                使用负数索引从右侧计数，使用负数 STEP 可按
                                逆序下载。例如，对于包含 15 个条目的播放列表，
                                使用 "-I 1:3,7,-5::2" 将下载索引为 1、2、3、7、
                                11、13、15 的条目
--min-filesize SIZE             若文件大小小于 SIZE 则中止下载，例如 50k 或 44.6M
--max-filesize SIZE             若文件大小大于 SIZE 则中止下载，例如 50k 或 44.6M
--date DATE                     仅下载在该日期上传的视频。日期可以是 "YYYYMMDD"，
                                或 [now|today|yesterday][-N[day|week|month|year]] 格式。
                                例如，"--date today-2weeks" 仅下载两周前同一天上传的视频
--datebefore DATE               仅下载在该日期或之前上传的视频。接受的日期格式与 --date 相同
--dateafter DATE                仅下载在该日期或之后上传的视频。接受的日期格式与 --date 相同
--match-filters FILTER          通用视频过滤器。任何 "OUTPUT TEMPLATE" 字段都可以与数字或字符串，
                                使用 "Filtering Formats" 中定义的运算符进行比较。
                                也可以只指定一个字段，以检查该字段是否存在；使用 "!field" 检查
                                该字段是否不存在；使用 "&" 检查多个条件。如有需要，使用 "\" 转义
                                "&" 或引号。若多次使用，只要满足其中至少一个条件，过滤器即匹配。
                                例如，--match-filters !is_live --match-filters "like_count>?100 &
                                description~='(?i)\bcats \& dogs\b'" 仅匹配以下视频：非直播视频，
                                或点赞数超过 100（或点赞数字段不可用）且描述中包含短语 "cats &
                                dogs"（不区分大小写）的视频。使用 "--match-filters -" 可交互式地
                                询问是否下载每个视频
--no-match-filters              不使用任何 --match-filters（默认）
--break-match-filters FILTER    与 "--match-filters" 相同，但视频被拒绝时停止下载过程
--no-break-match-filters        不使用任何 --break-match-filters（默认）
--no-playlist                   若 URL 同时指向视频和播放列表，则仅下载视频
--yes-playlist                  若 URL 同时指向视频和播放列表，则下载播放列表
--age-limit YEARS               仅下载适合指定年龄的视频
--download-archive FILE         仅下载未列在归档文件中的视频，并将所有已下载视频的 ID 记录到其中
--no-download-archive           不使用归档文件（默认）
--max-downloads NUMBER          下载 NUMBER 个文件后中止
--break-on-existing             遇到 --download-archive 所指定归档中的文件时，停止下载过程
--no-break-on-existing          遇到归档中的文件时不停止下载过程（默认）
--break-per-input               使 --max-downloads、--break-on-existing、--break-match-filters
                                和自动编号按每个输入 URL 分别重置
--no-break-per-input            --break-on-existing 等选项会终止整个下载队列
--skip-playlist-after-errors N  允许的失败次数，超过后跳过播放列表中的其余条目

下载选项：

-N, --concurrent-fragments N    同时下载的 dash/hlsnative 视频分片数量
                                （默认为 1）
-r, --limit-rate RATE           最大下载速率，单位为字节每秒，
                                例如 50K 或 4.2M
--throttled-rate RATE           最低下载速率，单位为字节每秒。低于该速率时
                                视为被限速，视频数据将被重新提取，
                                例如 100K
-R, --retries RETRIES           重试次数（默认为 10），或设为 "infinite"
--file-access-retries RETRIES   文件访问出错时的重试次数（默认为 3），
                                或设为 "infinite"
--fragment-retries RETRIES      分片的重试次数（默认为 10），或设为 "infinite"
                                （适用于 DASH、hlsnative 和 ISM）
--retry-sleep [TYPE:]EXPR       重试之间的等待时间（秒），可选择加上重试类型前缀
                                （http（默认）、fragment、file_access、extractor），
                                以指定等待时间应用于哪种重试。EXPR 可以是数字、
                                linear=START[:END[:STEP=1]] 或 exp=START[:END[:BASE=2]]。
                                此选项可多次使用，为不同的重试类型设置等待时间，例如
                                --retry-sleep linear=1::2 --retry-sleep fragment:exp=1:20
--skip-unavailable-fragments    跳过 DASH、hlsnative 和 ISM 下载中不可用的分片（默认）
                                （别名：--no-abort-on-unavailable-fragments）
--abort-on-unavailable-fragments
                                若分片不可用则中止下载
                                （别名：--no-skip-unavailable-fragments）
--keep-fragments                下载完成后保留磁盘上已下载的分片
--no-keep-fragments             下载完成后删除已下载的分片（默认）
--buffer-size SIZE              下载缓冲区大小，例如 1024 或 16K（默认为 1024）
--resize-buffer                 缓冲区大小将从 --buffer-size 的初始值自动调整（默认）
--no-resize-buffer              不自动调整缓冲区大小
--http-chunk-size SIZE          基于分块的 HTTP 下载中每个分块的大小，例如 10485760 或 10M
                                （默认禁用）。可能有助于绕过 Web 服务器施加的带宽限速（实验性功能）
--playlist-random               以随机顺序下载播放列表中的视频
--lazy-playlist                 在接收到播放列表条目时即进行处理。此选项会禁用 n_entries、
                                --playlist-random 和 --playlist-reverse
--no-lazy-playlist              仅在整个播放列表解析完成后才处理其中的视频（默认）
--hls-use-mpegts                HLS 视频使用 mpegts 容器，使部分播放器可以在下载过程中播放视频，
                                并降低下载中断时文件损坏的可能性。直播流默认启用此选项
--no-hls-use-mpegts             HLS 视频不使用 mpegts 容器。非直播流下载时为默认设置
--download-sections REGEX       仅下载与正则表达式匹配的章节。以 "*" 开头表示时间范围而非章节。
                                负数时间戳从末尾开始计算。"*from-url" 可用于下载从 URL 中提取的
                                "start_time" 和 "end_time" 之间的内容。需要 ffmpeg。
                                此选项可多次使用以下载多个片段，例如
                                --download-sections "*10:15-inf" --download-sections "intro"
--downloader [PROTO:]NAME       外部下载器的名称或路径，可选择加上协议前缀
                                （http、ftp、m3u8、dash、rtmp），以指定其用于的协议。
                                目前支持 native、aria2c、axel、curl、ffmpeg、httpie、wget。
                                可多次使用此选项为不同协议设置不同的下载器。例如
                                --downloader aria2c --downloader "dash,m3u8:native"
                                将 aria2c 用于 http/ftp 下载，将原生下载器用于 dash/m3u8 下载
                                （别名：--external-downloader）
--downloader-args NAME:ARGS     传递给外部下载器的参数。以冒号 ":" 分隔下载器名称和参数。
                                对于 ffmpeg，可使用与 --postprocessor-args 相同的语法将参数
                                传递到不同位置。可多次使用此选项为不同下载器提供不同参数
                                （别名：--external-downloader-args）

文件系统选项：

-a, --batch-file FILE           包含待下载 URL 的文件（"-" 表示标准输入），
                                每行一个 URL。以 "#"、";" 或 "]" 开头的行
                                视为注释并忽略
--no-batch-file                 不从批处理文件读取 URL（默认）
-P, --paths [TYPES:]PATH        文件的下载路径。使用冒号 ":" 分隔文件类型
                                与路径。支持与 --output 相同的所有 TYPES。
                                此外，还可以指定 "home"（默认）和 "temp"
                                路径。所有中间文件会先下载到 temp 路径，
                                下载完成后再移动到 home 路径。如果 --output
                                为绝对路径，则忽略此选项
-o, --output [TYPES:]TEMPLATE   输出文件名模板；详见 "OUTPUT
                                TEMPLATE"
--output-na-placeholder TEXT    --output 中不可用字段的占位符（默认："NA"）
--restrict-filenames            将文件名限制为仅包含 ASCII 字符，并避免
                                文件名中出现 "&" 和空格
--no-restrict-filenames         允许文件名中包含 Unicode 字符、"&" 和空格
                                （默认）
--windows-filenames             强制文件名兼容 Windows
--no-windows-filenames          仅做最低限度的文件名清理
--trim-filenames LENGTH         将文件名长度（不含扩展名）限制为指定的
                                字符数
-w, --no-overwrites             不覆盖任何文件
--force-overwrites              覆盖所有视频及元数据文件。此选项包含
                                --no-continue
--no-force-overwrites           不覆盖视频，但覆盖相关文件（默认）
-c, --continue                  续传部分下载的文件/分片（默认）
--no-continue                   不续传部分下载的分片。如果文件未分片，
                                则重新开始下载整个文件
--part                          使用 .part 文件，而不是直接写入输出文件
                                （默认）
--no-part                       不使用 .part 文件，直接写入输出文件
--mtime                         使用 Last-modified 响应头设置文件修改时间
--no-mtime                      不使用 Last-modified 响应头设置文件修改
                                时间（默认）
--write-description             将视频描述写入 .description 文件
--no-write-description          不写入视频描述（默认）
--write-info-json               将视频元数据写入 .info.json 文件
                                （可能包含个人信息）
--no-write-info-json            不写入视频元数据（默认）
--write-playlist-metafiles      使用 --write-info-json、--write-description
                                等选项时，除视频元数据外，还写入播放列表
                                元数据（默认）
--no-write-playlist-metafiles   使用 --write-info-json、--write-description
                                等选项时，不写入播放列表元数据
--clean-info-json               从 infojson 中移除部分内部元数据，例如
                                文件名（默认）
--no-clean-info-json            将所有字段写入 infojson
--write-comments                获取视频评论并放入 infojson。若已知提取
                                速度较快，即使未使用此选项也会获取评论
                                （别名：--get-comments）
--no-write-comments             除非已知提取速度较快，否则不获取视频评论
                                （别名：--no-get-comments）
--load-info-json FILE           包含视频信息的 JSON 文件（通过
                                "--write-info-json" 选项创建）
--cookies FILE                  读取和导出 Cookie 的 Netscape 格式文件
--no-cookies                    不从文件读取或导出 Cookie（默认）
--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]
                                加载 Cookie 的浏览器名称。目前支持：brave、
                                chrome、chromium、edge、firefox、opera、
                                safari、vivaldi、whale。可选地，可用各自的
                                分隔符指定用于在 Linux 上解密 Chromium
                                Cookie 的 KEYRING、加载 Cookie 所用的
                                PROFILE 名称/路径，以及 Firefox 的
                                CONTAINER 名称（"none" 表示不使用容器）。
                                默认情况下，使用最近访问的配置文件中的
                                所有容器。目前支持的 KEYRING 有：basictext、
                                gnomekeyring、kwallet、kwallet5、kwallet6
--no-cookies-from-browser       不从浏览器加载 Cookie（默认）
--cache-dir DIR                 yt-dlp 可永久存储部分已下载信息（如 client
                                ID 和签名）的文件系统位置。默认为
                                ${XDG_CACHE_HOME}/yt-dlp
--no-cache-dir                  禁用文件系统缓存
--rm-cache-dir                  删除所有文件系统缓存文件

缩略图选项：

--write-thumbnail               将缩略图写入磁盘
--no-write-thumbnail            不将缩略图写入磁盘（默认）
--write-all-thumbnails          将所有格式的缩略图写入磁盘
--list-thumbnails               列出每个视频可用的缩略图。
                                除非使用 --no-simulate，否则为模拟运行

网络快捷方式选项：

--write-link                    写入网络快捷方式文件，具体格式取决于当前平台
                                （.url、.webloc 或 .desktop）。该 URL 可能会被操作系统缓存
--write-url-link                写入 Windows 的 .url 网络快捷方式。操作系统会根据文件路径缓存该 URL
--write-webloc-link             写入 macOS 的 .webloc 网络快捷方式
--write-desktop-link            写入 Linux 的 .desktop 网络快捷方式
## 详细程度与模拟选项：
-q, --quiet                     启用静默模式。与 --verbose 一起使用时，
                                将日志输出到 stderr
--no-quiet                      关闭静默模式（默认）
--no-warnings                   忽略警告
-s, --simulate                  不下载视频，也不向磁盘写入任何内容
--no-simulate                   即使使用了打印或列出选项，也下载视频
--ignore-no-formats-error       忽略 "No video formats" 错误。适用于即使
                                视频实际上无法下载，也要提取元数据的场景
                                （实验性）
--no-ignore-no-formats-error    未找到可下载的视频格式时抛出错误（默认）
--skip-download                 不下载视频，但写入所有相关文件
                                （别名：--no-download）
-O, --print [WHEN:]TEMPLATE     要打印到屏幕的字段名或输出模板，可选择以
                                用 ":" 分隔的时机作为前缀。WHEN 的取值与
                                --use-postprocessor 相同（默认：video）。
                                隐含 --quiet。除非使用了 --no-simulate 或
                                WHEN 的后续阶段，否则隐含 --simulate。
                                此选项可多次使用
--print-to-file [WHEN:]TEMPLATE FILE
                                将给定模板追加到文件中。WHEN 和 TEMPLATE
                                的取值与 --print 相同。FILE 使用与输出
                                模板相同的语法。此选项可多次使用
-j, --dump-json                 静默输出，但为每个视频打印 JSON 信息。
                                除非使用 --no-simulate，否则隐含模拟。
                                可用字段的说明见 "OUTPUT TEMPLATE"
-J, --dump-single-json          静默输出，但为每个传入的 URL 或 infojson
                                打印 JSON 信息。除非使用 --no-simulate，
                                否则隐含模拟。如果 URL 指向播放列表，
                                则整个播放列表信息将输出为单行
--force-write-archive           只要没有出现错误，即使使用了 -s 或其他
                                模拟选项，也强制写入下载存档条目
                                （别名：--force-download-archive）
--newline                       将进度条输出为多行
--no-progress                   不打印进度条
--progress                      即使在静默模式下也显示进度条
--console-title                 在控制台标题栏中显示进度
--progress-template [TYPES:]TEMPLATE
                                进度输出模板，可选择以 "download:"（默认）、
                                "download-title:"（控制台标题）、
                                "postprocess:" 或 "postprocess-title:"
                                之一作为前缀。视频字段可通过 "info" 键访问，
                                进度属性可通过 "progress" 键访问。例如：
                                --console-title --progress-template
                                "download-title:%(info.id)s-%(progress.eta)s"
--progress-delta SECONDS        进度输出之间的时间间隔（默认：0）
-v, --verbose                   打印各种调试信息
--dump-pages                    以 base64 编码打印已下载的页面，用于排查
                                问题（非常详细）
--write-pages                   将已下载的中间页面写入当前目录的文件中，
                                用于排查问题
--print-traffic                 显示发送和接收的 HTTP 流量

变通方案：

--encoding ENCODING             强制使用指定的编码（实验性）
--legacy-server-connect         显式允许与不支持 RFC 5746 安全重协商的服务器建立 HTTPS 连接
--no-check-certificates         禁止 HTTPS 证书验证
--prefer-insecure               使用未加密的连接获取视频信息
--add-headers FIELD:VALUE       指定自定义 HTTP 请求头及其值，二者以冒号 ":" 分隔。可多次使用此选项
--bidi-workaround               为不支持双向文本的终端提供变通支持。需要 PATH 中存在 bidiv 或 fribidi 可执行文件
--sleep-requests SECONDS        数据提取期间，每次请求之间休眠的秒数
--sleep-interval SECONDS        每次下载前休眠的秒数。与 --max-sleep-interval 一起使用时，此值为最短休眠时间（别名：--min-sleep-interval）
--max-sleep-interval SECONDS    最长休眠秒数。只能与 --min-sleep-interval 一起使用
--sleep-subtitles SECONDS       每次下载字幕前休眠的秒数

视频格式选项：

-f, --format FORMAT             视频格式代码，详见 "FORMAT SELECTION"
                                部分
-S, --format-sort SORTORDER     按给定字段对格式排序，详见
                                "Sorting Formats" 部分
--format-sort-reset             忽略之前用户指定的排序顺序，
                                并恢复为默认值
--format-sort-force             让用户指定的排序顺序优先于所有字段，
                                详见 "Sorting Formats" 部分（别名：--S-force）
--no-format-sort-force          某些字段优先于用户指定的排序顺序（默认）
--video-multistreams            允许将多个视频流合并为单个文件
--no-video-multistreams         每个输出文件仅下载一个视频流（默认）
--audio-multistreams            允许将多个音频流合并为单个文件
--no-audio-multistreams         每个输出文件仅下载一个音频流（默认）
--prefer-free-formats           在画质相同的情况下，优先选择免费容器的
                                视频格式，而非非免费容器。配合 "-S ext" 使用
                                可严格优先选择免费容器，不考虑画质
--no-prefer-free-formats        不对免费容器给予任何特别优先（默认）
--check-formats                 确保仅从实际可下载的格式中选择
--check-all-formats             检查所有格式是否实际可下载
--no-check-formats              不检查格式是否实际可下载
-F, --list-formats              列出每个视频的可用格式。
                                除非使用 --no-simulate，否则仅模拟运行
--merge-output-format FORMAT    合并格式时可使用的容器，以 "/" 分隔，例如 "mp4/mkv"。
                                若无需合并则忽略。（当前支持：avi、flv、mkv、mov、mp4、webm）

字幕选项：

--write-subs                    写入字幕文件
--no-write-subs                 不写入字幕文件（默认）
--write-auto-subs               写入自动生成的字幕文件
                                （别名：--write-automatic-subs）
--no-write-auto-subs            不写入自动生成的字幕
                                （默认）（别名：--no-write-automatic-subs）
--list-subs                     列出每个视频可用的字幕。
                                除非使用 --no-simulate，否则仅模拟运行
--sub-format FORMAT             字幕格式；接受以 "/" 分隔的格式偏好列表，
                                例如 "srt" 或 "ass/srt/best"
--sub-langs LANGS               要下载的字幕语言（可使用正则表达式），或以逗号分隔的
                                "all"，例如 --sub-langs "en.*,ja"（其中 "en.*" 是
                                匹配 "en" 后接零个或多个任意字符的正则表达式）。
                                在语言代码前加 "-" 可将其从所请求的语言中排除，例如
                                --sub-langs all,-live_chat。使用 --list-subs 可查看
                                可用语言标签列表

认证选项：

-u, --username USERNAME         使用此账户 ID 登录
-p, --password PASSWORD         账户密码。若省略此选项，yt-dlp 将以交互方式询问
-2, --twofactor TWOFACTOR       双因素认证码
-n, --netrc                     使用 .netrc 认证数据
--netrc-location PATH           .netrc 认证数据的位置；可以是文件路径或其所在目录。
                                默认为 ~/.netrc
--netrc-cmd NETRC_CMD           用于获取提取器凭据的命令。
--video-password PASSWORD       视频专用密码
--ap-mso MSO                    Adobe Pass 多系统运营商（电视服务提供商）标识符，
                                可使用 --ap-list-mso 查看可用的 MSO 列表
--ap-username USERNAME          多系统运营商账户登录名
--ap-password PASSWORD          多系统运营商账户密码。若省略此选项，yt-dlp 将以
                                交互方式询问
--ap-list-mso                   列出所有受支持的多系统运营商
--client-certificate CERTFILE   PEM 格式的客户端证书文件路径。可包含私钥
--client-certificate-key KEYFILE
                                客户端证书对应的私钥文件路径
--client-certificate-password PASSWORD
                                客户端证书私钥的密码（若已加密）。若未提供且私钥已加密，
                                yt-dlp 将以交互方式询问

后处理选项：

-x, --extract-audio             将视频文件转换为纯音频文件
                                （需要 ffmpeg 和 ffprobe）
--audio-format FORMAT           使用 -x 时转换音频的目标格式。（当前支持：best（默认）、
                                aac、alac、flac、m4a、mp3、opus、vorbis、
                                wav）。可使用与 --remux-video 类似的语法指定多条规则
--audio-quality QUALITY         使用 -x 转换音频时使用的 ffmpeg 音频质量。VBR 模式下填写 0（最好）
                                到 10（最差）之间的值，或固定码率，如 128K（默认 5）
--remux-video FORMAT            在必要时将视频重新封装到其他容器中（当前支持：avi、flv、
                                gif、mkv、mov、mp4、webm、aac、aiff、alac、
                                flac、m4a、mka、mp3、ogg、opus、vorbis、
                                wav）。若目标容器不支持该视频或音频编解码器，重新封装将失败。
                                可指定多条规则，例如
                                "aac>m4a/mov>mp4/mkv" 会将 aac 重新封装为 m4a，
                                mov 重新封装为 mp4，其他所有格式重新封装为 mkv
--recode-video FORMAT           在必要时将视频重新编码为其他格式。语法和支持的格式
                                与 --remux-video 相同
--postprocessor-args NAME:ARGS  将这些参数传递给后处理器。
                                指定后处理器或可执行文件名称，并用冒号 ":" 分隔参数，
                                以便将参数传递给指定的后处理器或可执行文件。支持的 PP 有：
                                Merger、ModifyChapters、SplitChapters、
                                ExtractAudio、VideoRemuxer、VideoConvertor、
                                Metadata、EmbedSubtitle、EmbedThumbnail、
                                SubtitlesConvertor、ThumbnailsConvertor、
                                FixupStretched、FixupM4a、FixupM3u8、
                                FixupTimestamp 和 FixupDuration。支持的可执行文件有：AtomicParsley、
                                FFmpeg 和 FFprobe。也可以使用 "PP+EXE:ARGS"，
                                仅在指定后处理器调用该可执行文件时才传递参数。
                                此外，对于 ffmpeg/ffprobe，可在前缀后添加 "_i"/"_o"，
                                并可选择附加数字，以便将参数传递到指定输入/输出文件之前，例如 --ppa
                                "Merger+ffmpeg_i1:-v quiet"。可多次使用此选项，
                                为不同的后处理器传递不同参数。
                                （别名：--ppa）
-k, --keep-video                后处理完成后保留磁盘上的中间视频文件
--no-keep-video                 后处理完成后删除中间视频文件（默认）
--post-overwrites               覆盖后处理生成的文件（默认）
--no-post-overwrites            不覆盖后处理生成的文件
--embed-subs                    将字幕嵌入视频中（仅适用于 mp4、
                                webm 和 mkv 视频）
--no-embed-subs                 不嵌入字幕（默认）
--embed-thumbnail               将缩略图作为封面嵌入视频中
--no-embed-thumbnail            不嵌入缩略图（默认）
--embed-metadata                将元数据嵌入视频文件。若存在章节或 infojson，也会一并嵌入，
                                除非使用了 --no-embed-chapters 或 --no-embed-info-json
                                （别名：--add-metadata）
--no-embed-metadata             不向文件添加元数据（默认）
                                （别名：--no-add-metadata）
--embed-chapters                向视频文件添加章节标记
                                （别名：--add-chapters）
--no-embed-chapters             不添加章节标记（默认）（别名：
                                --no-add-chapters）
--embed-info-json               将 infojson 作为附件嵌入 mkv/mka 视频文件
--no-embed-info-json            不将 infojson 作为附件嵌入视频文件
--parse-metadata [WHEN:]FROM:TO
                                从其他字段解析标题、艺术家等附加元数据；详见“修改元数据”
                                部分。“WHEN”的支持值与 --use-postprocessor 相同
                                （默认：pre_process）
--replace-in-metadata [WHEN:]FIELDS REGEX REPLACE
                                使用给定的正则表达式替换元数据字段中的文本。
                                可多次使用此选项。“WHEN”的支持值与 --use-postprocessor 相同
                                （默认：pre_process）
--xattrs                        将元数据写入视频文件的扩展属性
                                （使用 Dublin Core 和 XDG 标准）
--concat-playlist POLICY        拼接播放列表中的视频。可选值为
                                “never”、“always”或“multi_video”
                                （默认；仅当视频构成单个节目时）。所有视频文件必须具有
                                相同的编解码器和流数量，才能拼接。可与 "--paths" 和 "--output" 一起使用
                                "pl_video:" 前缀，以设置拼接后文件的输出文件名。详见
                                “输出模板”
--fixup POLICY                  自动修正文件的已知问题。可选值为：never（不做任何处理）、warn（仅
                                发出警告）、detect_or_warn（默认；能修复时修复文件，
                                否则发出警告）、force（即使文件已存在也尝试修复）
--ffmpeg-location PATH          ffmpeg 可执行文件的位置；可以是可执行文件的路径或其所在目录
--exec [WHEN:]CMD               执行命令，可选择以执行时机作为前缀，两者以 ":" 分隔。
                                “WHEN”的支持值与 --use-postprocessor 相同（默认：
                                after_move）。可使用与输出模板相同的语法，将任意字段作为
                                命令参数传递；但出于安全考虑，仅允许以下转换：
                                “i”/“d”（有符号十进制整数）、“f”（浮点十进制数）和
                                “q”（shell 转义）。若未传递任何字段，则会在命令末尾附加
                                %(filepath,_filename|)q。可多次使用此选项
--no-exec                       移除之前定义的所有 --exec
--convert-subs FORMAT           将字幕转换为其他格式（当前支持：ass、lrc、srt、vtt）。
                                使用 "--convert-subs none" 可禁用转换（默认）（别名：--convert-
                                subtitles）
--convert-thumbnails FORMAT     将缩略图转换为其他格式（当前支持：jpg、png、webp）。
                                可使用与 "--remux-video" 类似的语法指定多条规则。使用 "--convert-
                                thumbnails none" 可禁用转换（默认）
--split-chapters                根据内部章节将视频拆分为多个文件。可与 "--paths" 和 "--output" 一起使用
                                "chapter:" 前缀，以设置拆分后文件的输出文件名。详见
                                “输出模板”
--no-split-chapters             不根据章节拆分视频（默认）
--remove-chapters REGEX         移除标题与给定正则表达式匹配的章节。语法与
                                --download-sections 相同。可多次使用此选项
--no-remove-chapters            不从文件中移除任何章节（默认）
--force-keyframes-at-cuts       在下载、拆分或移除片段时，在剪切点强制插入关键帧。
                                由于需要重新编码，速度较慢，但生成的视频在剪切点附近
                                可能出现更少的瑕疵
--no-force-keyframes-at-cuts    剪切或拆分时不在章节附近强制插入关键帧（默认）
--use-postprocessor NAME[:ARGS]
                                要启用的插件后处理器名称（区分大小写），以及
                                （可选）传递给它的参数，两者以 ":" 分隔。ARGS 是以 ";" 分隔的
                                NAME=VALUE 列表。“when”参数决定后处理器的调用时机，可选值为：
                                “pre_process”（视频提取之后）、
                                “after_filter”（视频通过过滤器之后）、
                                “video”（--format 之后；--print/--output 之前）、
                                “before_dl”（每个视频下载之前）、“post_process”（每个
                                视频下载之后；默认）、“after_move”
                                （视频文件移动到最终位置之后）、“after_video”（下载并处理
                                某个视频的所有格式之后），或
                                “playlist”（播放列表结束时）。可多次使用此选项
                                以添加不同的后处理器

SponsorBlock 选项：

使用 [SponsorBlock API](https://sponsor.ajay.app)，为下载的 YouTube 视频创建章节条目，
或移除各类片段（赞助、片头等）。

--sponsorblock-mark CATS        为指定的 SponsorBlock 类别创建章节，类别之间
                                用逗号分隔。可用类别包括 sponsor、intro、outro、
                                selfpromo、preview、filler、interaction、
                                music_offtopic、hook、poi_highlight、chapter、
                                all 和 default（=all）。在类别前加 "-" 可将其排除。
                                类别说明参见 [1]。例如 --sponsorblock-mark
                                all,-preview
                                [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
--sponsorblock-remove CATS      从视频文件中移除指定的 SponsorBlock 类别，类别之间
                                用逗号分隔。如果某个类别同时出现在 mark 和 remove 中，
                                则以 remove 为准。语法和可用类别与
                                --sponsorblock-mark 相同，但 "default" 指的是
                                "all,-filler"，且 poi_highlight、chapter 不可用
--sponsorblock-chapter-title TEMPLATE
                                由 --sponsorblock-mark 创建的 SponsorBlock 章节标题
                                的输出模板。可用字段仅有 start_time、end_time、
                                category、categories、name、category_names。
                                默认为 "[SponsorBlock]: %(category_names)l"
--no-sponsorblock               同时禁用 --sponsorblock-mark 和
                                --sponsorblock-remove
--sponsorblock-api URL          SponsorBlock API 地址，默认为
                                https://sponsor.ajay.app

提取器选项：

--extractor-retries RETRIES     对已知提取器错误的重试次数（默认为 3），
                                或 "infinite"
--allow-dynamic-mpd             处理动态 DASH 清单（默认）
                                （别名：--no-ignore-dynamic-mpd）
--ignore-dynamic-mpd            不处理动态 DASH 清单
                                （别名：--no-allow-dynamic-mpd）
--hls-split-discontinuity       在广告插播等不连续点处，将 HLS 播放列表拆分为
                                不同格式
--no-hls-split-discontinuity    不在广告插播等不连续点处将 HLS 播放列表拆分为
                                不同格式（默认）
--extractor-args IE_KEY:ARGS    将 ARGS 参数传递给 IE_KEY 提取器。
                                详情参见 "EXTRACTOR ARGUMENTS"。可多次使用此选项，
                                为不同提取器提供参数

预设别名：

为方便使用而预定义的别名。注意，未来版本的 yt-dlp 可能会新增或调整预设，但现有预设名称不会被更改或删除

-t mp3                          -f 'ba[acodec^=mp3]/ba/b' -x --audio-format
                                mp3

-t aac                          -f
                                'ba[acodec^=aac]/ba[acodec^=mp4a.40.]/ba/b'
                                -x --audio-format aac

-t mp4                          --merge-output-format mp4 --remux-video mp4
                                -S vcodec:h264,lang,quality,res,fps,hdr:12,a
                                codec:aac

-t mkv                          --merge-output-format mkv --remux-video mkv

-t sleep                        --sleep-subtitles 5 --sleep-requests 0.75
                                --sleep-interval 10 --max-sleep-interval 20

配置

你可以通过在配置文件中放置任何受支持的命令行选项来配置 yt-dlp。配置文件会从以下位置加载：

  1. 主配置：

    • 传给 --config-locations 的文件

  2. 便携配置：（推荐用于便携安装）

    • 如果使用二进制文件，则为与该二进制文件位于同一目录中的 yt-dlp.conf
    • 如果从源代码运行，则为 yt_dlp 上级目录中的 yt-dlp.conf

  3. 主目录配置：

    • 传给 -P 的主目录路径中的 yt-dlp.conf
    • 如果未指定 -P，则搜索当前目录

  4. 用户配置：

    • ${XDG_CONFIG_HOME}/yt-dlp.conf
    • ${XDG_CONFIG_HOME}/yt-dlp/config（推荐用于 Linux/macOS）
    • ${XDG_CONFIG_HOME}/yt-dlp/config.txt
    • ${APPDATA}/yt-dlp.conf
    • ${APPDATA}/yt-dlp/config（推荐用于 Windows）
    • ${APPDATA}/yt-dlp/config.txt
    • ~/yt-dlp.conf
    • ~/yt-dlp.conf.txt
    • ~/.yt-dlp/config
    • ~/.yt-dlp/config.txt

    另请参阅：关于环境变量的说明

  5. 系统配置：

    • /etc/yt-dlp.conf
    • /etc/yt-dlp/config
    • /etc/yt-dlp/config.txt

例如，使用以下配置文件时，yt-dlp 将始终提取音频、复制修改时间、使用代理，并将所有视频保存到主目录下的 YouTube 目录中：

# Lines starting with # are comments

# Always extract audio
-x

# Copy the mtime
--mtime

# Use this proxy
--proxy 127.0.0.1:3128

# Save all videos under YouTube directory in your home directory
-o ~/YouTube/%(title)s.%(ext)s

注意：配置文件中的选项与普通命令行调用中使用的选项（即开关）完全相同。因此，- 或 -- 之后不得有空白字符，例如 -o 或 --proxy 是正确的，而 - o 或 -- proxy 则不正确。必要时还须像在 UNIX shell 中一样加上引号。

你可以使用 --ignore-config 来禁用某次 yt-dlp 运行时的所有配置文件。如果在任何配置文件中发现 --ignore-config，则不会再加载其他配置。例如，若便携配置文件中包含该选项，则会阻止加载主目录、用户和系统配置。此外，（出于向后兼容的考虑）如果系统配置文件中包含 --ignore-config，则不会加载用户配置。

配置文件编码

如果存在 BOM，配置文件会根据 UTF BOM 进行解码；否则，将使用系统区域设置中的编码进行解码。

如果希望以不同的编码解码你的文件，请在文件开头添加 # coding: ENCODING（例如 # coding: shift-jis）。该行之前不得有任何字符，包括空格或 BOM。

使用 netrc 进行身份验证

对于支持身份验证的提取器（通过 --username 和 --password 提供登录名和密码），你可能还希望配置自动保存凭据。这样每次执行 yt-dlp 时就无需将凭据作为命令行参数传入，也能避免明文密码被记录在 shell 命令历史中。你可以使用 .netrc 文件 按提取器单独配置。为此，你需要在 --netrc-location 指定的位置创建 .netrc 文件，并将其权限设置为仅你自己可读写：

touch ${HOME}/.netrc
chmod a-rwx,u+rw ${HOME}/.netrc

之后，你可以按以下格式为某个提取器添加凭据，其中 extractor 为该提取器的名称（小写）：

machine <extractor> login <username> password <password>

例如：

machine youtube login [email protected] password my_youtube_password
machine twitch login my_twitch_account_name password my_twitch_password

要启用 .netrc 文件的身份验证，需要向 yt-dlp 传入 --netrc，或将其写入配置文件。

.netrc 文件的默认位置为 ~（见下文）。

除使用 .netrc 文件外，你还可以配置自定义 shell 命令来为提取器提供凭据。.netrc 文件的缺点是将密码保存在明文文件中，而使用自定义命令可以避免这一问题。该命令通过 --netrc-cmd 参数指定，它需要以 netrc 格式输出凭据，并在成功时返回 0，其他返回值均视为错误。命令中的 {} 会被替换为提取器的名称，从而可以为对应的提取器选择正确的凭据。

例如，使用存储为 .authinfo.gpg 的加密 .netrc 文件：

yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' 'https://www.youtube.com/watch?v=YE7VzlLtp-4'
环境变量说明
  • 环境变量在 UNIX 上通常写作 ${VARIABLE}/$VARIABLE，在 Windows 上写作 %VARIABLE%；但本文档中统一写作 ${VARIABLE}
  • 对于路径类选项（例如 --output、--config-locations），yt-dlp 也允许在 Windows 上使用 UNIX 风格的变量
  • 未设置时，${XDG_CONFIG_HOME} 默认为 ~/.config，${XDG_CACHE_HOME} 默认为 ~/.cache
  • 在 Windows 上，若存在 ${HOME}，则 ~ 指向 ${HOME}；否则指向 ${USERPROFILE} 或 ${HOMEDRIVE}${HOMEPATH}
  • 在 Windows 上，${USERPROFILE} 一般指向 C:\Users\<user name>，${APPDATA} 指向 ${USERPROFILE}\AppData\Roaming

输出模板

-o 选项用于指定输出文件名的模板，而 -P 选项用于指定每种类型文件的保存路径。

简述： 直接跳转到示例。

-o 最简单的用法是在下载单个文件时不设置任何模板参数，例如 yt-dlp -o funny_video.flv "https://some/video"（像这样硬编码文件扩展名_并不推荐_，可能会导致某些后处理功能出错）。

它也可以包含特殊序列，在下载每个视频时会被替换。特殊序列可以按照 Python 字符串格式化操作 进行格式化，例如 %(NAME)s 或 %(NAME)05d。具体来说，它是一个百分号，后面跟着括号中的字段名，再后面是格式化操作。

括号中的字段名本身也支持一些特殊格式：

  1. 对象遍历：元数据中可用的字典和列表可以使用点 . 作为分隔符进行遍历，例如 %(tags.0)s、%(subtitles.en.-1.ext)s。可以使用冒号 : 进行 Python 风格的切片，例如 %(id.3:7)s、%(id.6:2:-1)s、%(formats.:.format_id)s。花括号 {} 可用于构建仅包含特定键的字典，例如 %(formats.:.{format_id,height})#j。空字段名 %()s 表示整个 infodict，例如 %(.{id,title})s。请注意，通过此方法可用的所有字段并未在下文全部列出。使用 -j 可以查看这些字段。

  2. 算术运算：可以对数值字段使用 +、- 和 * 进行简单的算术运算，例如 %(playlist_index+10)03d、%(n_entries+1-playlist_index)d

  3. 日期/时间格式化: 日期/时间字段可以按照 strftime 格式化 进行格式化，方法是在字段名后用 > 分隔并指定格式。例如 %(duration>%H-%M-%S)s、%(upload_date>%Y-%m-%d)s、%(epoch-3600>%H-%M-%S)s

  4. 备选字段: 可以用 , 分隔指定多个备选字段。例如 %(release_date>%Y,upload_date>%Y|Unknown)s

  5. 替换值: 可以用 & 分隔指定替换值，其格式遵循 str.format 迷你语言。如果字段不为空，则使用该替换值代替实际字段内容。此操作在考虑备选字段之后进行，因此只要任一备选字段不为空，就会使用替换值。例如 %(chapters&has chapters|no chapters)s、%(title&TITLE={:>20}|NO TITLE)s

  6. 默认值: 可以用 | 分隔指定字段为空时使用的字面默认值。该设置会覆盖 --output-na-placeholder。例如 %(uploader|Unknown)s

  7. 更多转换: 除常规格式类型 diouxXeEfFgGcrs 外，yt-dlp 还额外支持以下转换：B = Bytes（字节）、j = json（标志 # 用于美化输出，+ 用于保留 Unicode）、h = HTML 转义、l = 逗号分隔的列表（list，标志 # 改为以换行符分隔）、q = 为终端加引号的字符串（标志 # 可将列表拆分为不同参数）、D = 添加 Decimal 后缀（例如 10M）（标志 # 使用 1024 作为进制）、S = 清理后作为文件名（Sanitize，标志 # 使用 restricted 模式）

  8. Unicode 规范化: 格式类型 U 可用于 NFC Unicode 规范化。备用形式标志（#）会将规范化改为 NFD，转换标志 + 可用于 NFKC/NFKD 兼容等价规范化。例如 %(title)+.100U 即为 NFKC

综上所述，字段的通用语法为：

%(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type

此外，可以为各类元数据文件单独设置输出模板，不必与通用输出模板相同。方法是在文件类型后加冒号 : 并跟随模板。支持的文件类型包括 subtitle、thumbnail、description、annotation（已弃用）、infojson、link、pl_thumbnail、pl_description、pl_infojson、chapter、pl_video。例如 -o "%(title)s.%(ext)s" -o "thumbnail:%(title)s/%(title)s.%(ext)s" 会将缩略图放入与视频同名的文件夹中。若某个模板为空，则不会写入该类文件。例如 --write-thumbnail -o "thumbnail:" 仅会为播放列表写入缩略图，而不会为单个视频写入。

注意: 由于后处理（例如合并等），实际输出的文件名可能有所不同。请使用 --print after_move:filepath 获取所有后处理完成后的文件名。

可用字段如下：

  • id（字符串）：视频标识符
  • title（字符串）：视频标题
  • fulltitle（字符串）：忽略直播时间戳和通用标题的视频标题
  • ext（字符串）：视频文件扩展名
  • alt_title（字符串）：视频的次要标题
  • description（字符串）：视频简介
  • display_id（字符串）：视频的另一种标识符
  • uploader（字符串）：视频上传者的全名
  • uploader_id（字符串）：视频上传者的昵称或 ID
  • uploader_url（字符串）：视频上传者个人主页的 URL
  • license（字符串）：视频所采用的许可证名称
  • creators（列表）：视频的创作者
  • creator（字符串）：视频的创作者，以逗号分隔
  • timestamp（数字）：视频变为可用时的 UNIX 时间戳
  • upload_date（字符串）：视频上传日期（UTC，格式为 YYYYMMDD）
  • release_timestamp（数字）：视频发布时的 UNIX 时间戳
  • release_date（字符串）：视频发布日期（UTC，格式为 YYYYMMDD）
  • release_year（数字）：视频或专辑的发布年份（YYYY）
  • modified_timestamp（数字）：视频最后修改时的 UNIX 时间戳
  • modified_date（字符串）：视频最后修改日期（UTC，格式为 YYYYMMDD）
  • channel（字符串）：视频所属频道的全名
  • channel_id（字符串）：频道 ID
  • channel_url（字符串）：频道 URL
  • channel_follower_count（数字）：频道的粉丝数
  • channel_is_verified（布尔值）：该频道在平台上是否已认证
  • location（字符串）：视频拍摄的实际地点
  • duration（数字）：视频时长（秒）
  • duration_string（字符串）：视频时长（HH:mm:ss）
  • view_count（数字）：在平台上观看过该视频的用户数
  • concurrent_view_count（数字）：当前正在观看该视频的用户数。
  • like_count（数字）：视频的好评数
  • dislike_count（数字）：视频的差评数
  • repost_count（数字）：视频的转发数
  • average_rating（数字）：用户给出的平均评分，所用量表取决于网页
  • comment_count（数字）：视频的评论数（对于部分提取器，评论要到最后才会下载，因此无法使用此字段）
  • save_count（数字）：视频被保存或收藏的次数
  • age_limit（数字）：视频的年龄限制（岁）
  • live_status（字符串）：可选值为 "not_live"、"is_live"、"is_upcoming"、"was_live"、"post_live"（曾为直播，但点播版本尚未处理完成）
  • is_live（布尔值）：该视频是直播还是定长视频
  • was_live（布尔值）：该视频最初是否为直播
  • playable_in_embed（字符串）：该视频是否允许在其他网站的嵌入式播放器中播放
  • availability（字符串）：视频的可用性，可能的值为 "private"、"premium_only"、"subscriber_only"、"needs_auth"、"unlisted" 或 "public"
  • media_type（字符串）：网站分类的媒体类型，例如 "episode"、"clip"、"trailer"
  • start_time（数字）：URL 中指定的播放起始时间（秒）
  • end_time（数字）：URL 中指定的播放结束时间（秒）
  • extractor（字符串）：提取器名称
  • extractor_key（字符串）：提取器的键名
  • epoch（数字）：信息提取完成时的 Unix 纪元时间
  • autonumber（数字）：每次下载后递增的编号，从 --autonumber-start 开始，补零至 5 位
  • video_autonumber（数字）：每个视频后递增的编号
  • n_entries（数字）：播放列表中提取的项目总数
  • playlist_id（字符串）：包含该视频的播放列表标识符
  • playlist_title（字符串）：包含该视频的播放列表名称
  • playlist（字符串）：若有则为 playlist_title，否则为 playlist_id
  • playlist_count（数字）：播放列表中的项目总数。若未提取整个播放列表，则可能未知
  • playlist_index（数字）：视频在播放列表中的索引，根据最终索引补零
  • playlist_autonumber（数字）：视频在播放列表下载队列中的位置，根据播放列表总长度补零
  • playlist_uploader（字符串）：播放列表上传者的全名
  • playlist_uploader_id（字符串）：播放列表上传者的昵称或 ID
  • playlist_channel（字符串）：上传该播放列表的频道显示名称
  • playlist_channel_id（字符串）：上传该播放列表的频道标识符
  • playlist_webpage_url（字符串）：播放列表网页的 URL
  • webpage_url（字符串）：视频网页的 URL，将其提供给 yt-dlp 应得到相同结果
  • webpage_url_basename（字符串）：网页 URL 的基本名称
  • webpage_url_domain（字符串）：网页 URL 的域名
  • original_url（字符串）：用户提供的 URL（对于播放列表条目，与 webpage_url 相同）
  • categories（列表）：视频所属的分类列表
  • tags（列表）：分配给视频的标签列表
  • cast（列表）：演员列表 过滤格式 中的所有字段也都可以使用。

适用于属于某个逻辑章节或部分的视频：

  • chapter (字符串)：视频所属章节的名称或标题
  • chapter_number (数值)：视频所属章节的编号
  • chapter_id (字符串)：视频所属章节的 ID

适用于属于某个剧集或节目系列的剧集视频：

  • series (字符串)：视频剧集所属系列或节目的标题
  • series_id (字符串)：视频剧集所属系列或节目的 ID
  • season (字符串)：视频剧集所属季的标题
  • season_number (数值)：视频剧集所属季的编号
  • season_id (字符串)：视频剧集所属季的 ID
  • episode (字符串)：视频剧集的标题
  • episode_number (数值)：视频剧集在季中的编号
  • episode_id (字符串)：视频剧集的 ID

适用于属于音乐专辑的曲目或其一部分的媒体：

  • track (字符串)：曲目的标题
  • track_number (数值)：曲目在专辑或光盘中的编号
  • track_id (字符串)：曲目的 ID
  • artists (列表)：曲目的艺术家
  • artist (字符串)：曲目的艺术家，以逗号分隔
  • genres (列表)：曲目的流派
  • genre (字符串)：曲目的流派，以逗号分隔
  • composers (列表)：作品的作曲者
  • composer (字符串)：作品的作曲者，以逗号分隔
  • album (字符串)：曲目所属专辑的标题
  • album_type (字符串)：专辑的类型
  • album_artists (列表)：专辑中出现的所有艺术家
  • album_artist (字符串)：专辑中出现的所有艺术家，以逗号分隔
  • disc_number (数值)：曲目所属光盘或其他实体介质的编号

仅在使用 --download-sections 时可用，对于带有内部章节的视频，在使用 --split-chapters 时的 chapter: 前缀也可用：

  • section_title (字符串)：章节的标题
  • section_number (数值)：章节在文件中的编号
  • section_start (数值)：章节的开始时间，以秒为单位
  • section_end (数值)：章节的结束时间，以秒为单位

仅在 --print 中可用：

  • urls (字符串)：所有请求格式的 URL，每行一个
  • filename (字符串)：视频文件的名称。注意，实际文件名可能不同
  • formats_table (表格)：由 --list-formats 打印的视频格式表
  • thumbnails_table (表格)：由 --list-thumbnails 打印的缩略图格式表
  • subtitles_table (表格)：由 --list-subs 打印的字幕格式表
  • automatic_captions_table (表格)：由 --list-subs 打印的自动字幕格式表

仅在视频下载完成后可用（post_process/after_move）：

  • filepath：下载的视频文件的实际路径

仅在 --sponsorblock-chapter-title 中可用：

  • start_time (数值)：章节的开始时间，以秒为单位
  • end_time (数值)：章节的结束时间，以秒为单位
  • categories (列表)：章节所属的 SponsorBlock 分类
  • category (字符串)：章节所属的最小 SponsorBlock 分类
  • category_names (列表)：分类的友好名称
  • name (字符串)：最小分类的友好名称
  • type (字符串)：章节的 SponsorBlock 操作类型

在输出模板中引用时，每个上述序列都会被替换为与序列名称对应的实际值。例如，对于 -o %(title)s-%(id)s.%(ext)s，以及标题为 yt-dlp test video、ID 为 YE7VzlLtp-4 的 mp4 视频，会在当前目录中创建一个名为 yt-dlp test video-YE7VzlLtp-4.mp4 的文件。 注意：部分序列不一定存在，因为它们取决于特定提取器获取的元数据。这些序列将被替换为通过 --output-na-placeholder 指定的占位值（默认为 NA）。

提示：查看 -j 输出，以确定特定 URL 有哪些可用字段。

对于数字序列，可以使用数字相关格式化；例如，%(view_count)05d 会生成一个字符串，其中观看次数用零补齐到 5 个字符，如 00042。

输出模板还可以包含任意层级的路径，例如 -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s"，这会将每个视频下载到与该路径模板对应的目录中。任何缺失的目录都会被自动创建。

要在输出模板中使用百分号字面量，请使用 %%。要输出到标准输出，请使用 -o -。

当前默认模板为 %(title)s [%(id)s].%(ext)s。

在某些情况下，您可能不希望文件名中包含 中、空格或 & 等特殊字符，例如将下载的文件名传输到 Windows 系统，或通过不安全的 8bit 通道传输文件名时。此时，可添加 --restrict-filenames 标志以获得更短的标题。

输出模板示例
$ yt-dlp --print filename -o "test video.%(ext)s" ptd1NN40vMw
test video.webm    # Literal name with correct extension

$ yt-dlp --print filename -o "%(title)s.%(ext)s" ptd1NN40vMw
To'y!🤯😂🤦🏻‍♂️.webm    # All kinds of weird characters

$ yt-dlp --print filename -o "%(title)s.%(ext)s" ptd1NN40vMw --restrict-filenames
To_y.webm    # Restricted file name

# Download YouTube playlist videos in separate directory indexed by video order in a playlist
$ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# Download YouTube playlist videos in separate directories according to their uploaded year
$ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# Prefix playlist index with " - " separator, but only if it is available
$ yt-dlp -o "%(playlist_index&{} - |)s%(title)s.%(ext)s" YE7VzlLtp-4 "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# Download all playlists of YouTube channel/user keeping each playlist in separate directory:
$ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# Download Udemy course keeping each chapter in separate directory under MyVideos directory in your home
$ yt-dlp -u user -p password -P "~/MyVideos" -o "%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s" "https://www.udemy.com/java-tutorial"

# Download entire series season keeping each series and each season in separate directory under C:/MyVideos
$ yt-dlp -P "C:/MyVideos" -o "%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" "https://videomore.ru/kino_v_detalayah/5_sezon/367617"

# Download video as "C:\MyVideos\uploader\title.ext", subtitles as "C:\MyVideos\subs\uploader\title.ext"
# and put all temporary files in "C:\MyVideos\tmp"
$ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" YE7VzlLtp-4 --write-subs

# Download video as "C:\MyVideos\uploader\title.ext" and subtitles as "C:\MyVideos\uploader\subs\title.ext"
$ yt-dlp -P "C:/MyVideos" -o "%(uploader)s/%(title)s.%(ext)s" -o "subtitle:%(uploader)s/subs/%(title)s.%(ext)s" YE7VzlLtp-4 --write-subs

# Stream the video being downloaded to stdout
$ yt-dlp -o - YE7VzlLtp-4

格式选择

默认情况下，如果您不传递任何选项，yt-dlp 会尝试下载可用的最佳画质。这通常等同于使用 -f bestvideo*+bestaudio/best。但是，如果启用了多音频流（--audio-multistreams），默认格式会变为 -f bestvideo+bestaudio/best。同样，如果 ffmpeg 不可用，或者您使用 yt-dlp 输出到 stdout（-o -），默认值会变为 -f best/bestvideo+bestaudio。

弃用警告：最新版本的 yt-dlp 可以使用 ffmpeg 同时向 stdout 输出多个格式。因此，在未来版本中，此场景的默认值将设置为与普通下载类似的 -f bv*+ba/b。如果您想保留 -f b/bv+ba 设置，建议在配置选项中显式指定。

格式选择的通用语法为 -f FORMAT（或 --format FORMAT），其中 FORMAT 是一个选择器表达式，即描述您希望下载的一个或多个格式的表达式。

tl;dr: 直接跳转到示例。

最简单的情况是请求特定格式；例如，使用 -f 22 可以下载格式代码为 22 的格式。您可以使用 --list-formats 或 -F 获取特定视频的可用格式代码列表。注意，这些格式代码因提取器而异。

您还可以使用文件扩展名（目前支持 3gp、aac、flv、m4a、mp3、mp4、ogg、wav、webm），下载以单个文件提供的特定文件扩展名的最佳画质格式。例如，-f webm 将下载以单个文件提供的、扩展名为 webm 的最佳画质格式。

您可以使用 -f - 为每个视频交互式地提供格式选择器。

您还可以使用特殊名称来选择特定的边缘情况格式：

  • all：分别选择所有格式
  • mergeall：选择并合并所有格式（必须与 --audio-multistreams、--video-multistreams 或两者同时使用）
  • b*、best*：选择质量最好的、**包含视频或音频（或两者）**的格式（即 vcodec!=none or acodec!=none）
  • b、best：选择质量最好的、同时包含视频和音频的格式。等同于 best*[vcodec!=none][acodec!=none]
  • bv、bestvideo：选择质量最好的纯视频格式。等同于 best*[acodec=none]
  • bv*、bestvideo*：选择质量最好的包含视频的格式，该格式也可能包含音频。等同于 best*[vcodec!=none]
  • ba、bestaudio：选择质量最好的纯音频格式。等同于 best*[vcodec=none]
  • ba*、bestaudio*：选择质量最好的包含音频的格式，该格式也可能包含视频。等同于 best*[acodec!=none]（请勿使用！）
  • w*、worst*：选择质量最差的、包含视频或音频的格式
  • w、worst：选择质量最差的、同时包含视频和音频的格式。等同于 worst*[vcodec!=none][acodec!=none]
  • wv、worstvideo：选择质量最差的纯视频格式。等同于 worst*[acodec=none]
  • wv*、worstvideo*：选择质量最差的包含视频的格式，该格式也可能包含音频。等同于 worst*[vcodec!=none]
  • wa、worstaudio：选择质量最差的纯音频格式。等同于 worst*[vcodec=none]
  • wa*、worstaudio*：选择质量最差的包含音频的格式，该格式也可能包含视频。等同于 worst*[acodec!=none]

例如，要下载质量最差的纯视频格式，可以使用 -f worstvideo。不过，不建议使用 worst 及相关选项。当格式选择器为 worst 时，会选择各方面都最差的格式。大多数情况下，你真正想要的是文件体积最小的视频。因此，通常更好的做法是使用 -S +size，或更严格地使用 -S +size,+br,+res,+fps，而不是 -f worst。详情请参阅格式排序。

你可以使用 best<type>.<n> 选择某类型的第 n 优格式。例如，best.2 会选择第 2 优的组合格式；同理，bv*.3 会选择包含视频流的第 3 优格式。

如果你要下载多个视频，而它们可用的格式不完全相同，可以用斜杠指定偏好顺序。注意，斜杠左侧的格式优先级更高。例如，-f 22/17/18 会在格式 22 可用时下载它；否则在格式 17 可用时下载它；否则在格式 18 可用时下载它；如果都不可用，则提示没有合适的格式可供下载。

如果你要下载同一视频的多个格式，可以用逗号作为分隔符。例如，-f 22,17,18 会下载这三个格式（前提是它们都可用）。也可以结合优先级功能使用更复杂的写法，例如：-f 136/137/mp4/bestvideo,140/m4a/bestaudio。

你可以使用 -f <format1>+<format2>+... 将多个格式的视频和音频合并为一个文件（需要安装 ffmpeg）。例如，-f bestvideo+bestaudio 会下载质量最好的纯视频格式和质量最好的纯音频格式，并使用 ffmpeg 将它们封装到一起。

弃用警告：由于下述行为较为复杂且违反直觉，该行为将在未来被移除，多流将默认启用。届时会新增一个运算符，用于将格式限制为单一音频或单一视频。 除非使用 --video-multistreams，否则会忽略除第一个之外所有包含视频流的格式。同样，除非使用 --audio-multistreams，否则会忽略除第一个之外所有包含音频流的格式。例如，-f bestvideo+best+bestaudio --video-multistreams --audio-multistreams 会下载并合并全部 3 个给定格式，生成的文件将包含 2 个视频流和 2 个音频流。而 -f bestvideo+best+bestaudio --no-video-multistreams 只会下载并合并 bestvideo 和 bestaudio，因为已选择了包含视频流的另一个格式（bestvideo），所以 best 会被忽略。因此，格式的顺序很重要。-f best+bestaudio --no-audio-multistreams 只会下载 best，而 -f bestaudio+best --no-audio-multistreams 会忽略 best，只下载 bestaudio。

筛选格式

你还可以通过在方括号中添加条件来筛选视频格式，例如 -f "best[height=720]"（或 -f "[filesize>10M]"，因为没有选择器的筛选条件会被解释为 best）。

以下数值型元字段可以与 <、<=、>、>=、=（等于）、!=（不等于）进行比较：

  • filesize：字节数（如果事先已知）
  • filesize_approx：字节数的估计值
  • width：视频宽度（如果已知）
  • height：视频高度（如果已知）
  • aspect_ratio：视频宽高比（如果已知）
  • tbr：音频和视频的平均比特率，单位为 kbps
  • abr：平均音频比特率，单位为 kbps
  • vbr：平均视频比特率，单位为 kbps
  • asr：音频采样率，单位为赫兹
  • fps：帧率
  • audio_channels：音频声道数
  • stretched_ratio：视频像素的 宽:高（如果不是正方形）

此外，字符串型元字段也支持以下比较：=（等于）、^=（以……开头）、$=（以……结尾）、*=（包含）、~=（匹配正则表达式）：

  • url：视频 URL
  • ext：文件扩展名
  • acodec：正在使用的音频编解码器名称
  • vcodec：正在使用的视频编解码器名称
  • container：容器格式名称
  • protocol：实际下载所使用的协议，小写（http、https、rtmp、rtmpe、f4m、ism、http_dash_segments、m3u8 或 m3u8_native）
  • language：语言代码
  • dynamic_range：视频的动态范围
  • format_id：格式的简短描述
  • format：格式的人类可读描述
  • format_note：格式的附加信息
  • resolution：宽度和高度的文本描述

任何字符串比较都可以加上否定前缀 !，以得到相反的比较结果，例如 !*=（不包含）。如果字符串比较的比较值包含空格或除 ._- 之外的特殊字符，则需要使用双引号或单引号括起来。

注意：以上所有元字段都不能保证存在，因为这完全取决于提取器获取的元数据，即网站提供的元数据。提取器提供的任何其他字段也可以用于筛选。

如果某个值未知，则该格式会被排除，除非在运算符后加上问号（?）。筛选条件可以组合使用，因此 -f "bv[height<=?720][tbr>500]" 会选择最高 720p 的视频（或高度未知的视频），且比特率大于 500 kbps。你还可以将筛选条件与 all 一起使用，以下载所有满足条件的格式，例如 -f "all[vcodec=none]" 会选择所有纯音频格式。

格式选择器可以使用圆括号进行分组，例如 -f "(mp4,webm)[height<480]" 会下载高度小于 480 的最佳预合并 mp4 和 webm 格式。

排序格式

你可以使用 -S（--format-sort）更改判断 best 的标准。其通用格式为 --format-sort field1,field2...。 可用字段如下：

  • hasvid：优先选择包含视频流的格式
  • hasaud：优先选择包含音频流的格式
  • ie_pref：格式偏好
  • lang：提取器确定的语言偏好（例如原始语言优先于音频描述）
  • quality：格式的质量
  • source：来源偏好
  • proto：下载所用协议（https/ftps > http/ftp > m3u8_native/m3u8 > http_dash_segments> websocket_frag > f4f/f4m）
  • vcodec：视频编解码器（av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 > theora > 其他）
  • acodec：音频编解码器（flac/alac > wav/aiff > opus > vorbis > aac > mp4a > mp3 > ac4 > eac3 > ac3 > dts > 其他）
  • codec：等同于 vcodec,acodec
  • vext：视频扩展名（mp4 > mov > webm > flv > 其他）。如果使用了 --prefer-free-formats，则优先选择 webm。
  • aext：音频扩展名（m4a > aac > mp3 > ogg > opus > webm > 其他）。如果使用了 --prefer-free-formats，则顺序变为 ogg > opus > webm > mp3 > m4a > aac
  • ext：等同于 vext,aext
  • filesize：精确文件大小（如果事先已知）
  • fs_approx：近似文件大小
  • size：如果可用则为精确文件大小，否则为近似文件大小
  • height：视频高度
  • width：视频宽度
  • res：视频分辨率，按最小边计算。
  • fps：视频帧率
  • hdr：视频的动态范围（DV > HDR12 > HDR10+ > HDR10 > HLG > SDR）
  • channels：音频声道数
  • tbr：总平均比特率，单位为 kbps
  • vbr：平均视频比特率，单位为 kbps
  • abr：平均音频比特率，单位为 kbps
  • br：平均比特率，单位为 kbps，即 tbr/vbr/abr
  • asr：音频采样率，单位为 Hz

弃用警告：其中许多字段有（目前未记录的）别名，这些别名可能在未来版本中被移除。建议仅使用已记录的字段名。

除非另有说明，所有字段均按降序排序。若要反转顺序，请在字段前加上 +。例如，+res 优先选择分辨率最小的格式。此外，你还可以在字段后加上 : 并附上偏好值。例如，res:720 优先选择较大的视频，但不超过 720p；若不存在低于 720p 的视频，则选择最小的视频。对于 codec 和 ext，可以提供两个偏好值，第一个用于视频，第二个用于音频。例如，+codec:avc:m4a（等同于 +vcodec:avc,+acodec:m4a）将视频编解码器偏好设为 h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 > theora，将音频编解码器偏好设为 mp4a > aac > vorbis > opus > mp3 > ac3 > dts。你还可以使用 ~ 作为分隔符，使排序优先选择最接近所给值的结果。例如，filesize~1G 优先选择文件大小最接近 1 GiB 的格式。

字段 hasvid 和 ie_pref 始终拥有最高排序优先级，不受用户自定义顺序影响。可以通过使用 --format-sort-force 改变此行为。除此之外，默认顺序为：lang,quality,res,fps,hdr:12,vcodec,channels,acodec,size,br,asr,proto,ext,hasaud,source,id。提取器可以覆盖此默认顺序，但不能覆盖用户指定的顺序。

请注意，hdr 的默认值为 hdr:12，即不优先选择杜比视界（Dolby Vision）。做此选择是因为 DV 格式尚未与大多数设备完全兼容。未来可能会更改此设置。

如果你的格式选择器为 worst，则排序后选择最后一项。这意味着它会选择在所有方面都最差的格式。大多数情况下，你真正想要的是文件大小最小的视频。因此，通常更好的做法是使用 -f best -S +size,+br,+res,+fps。 如果多次使用 -S/--format-sort 选项，那么后面每个排序参数都会被添加到之前参数的前面，并且任何重复字段只保留优先级最高的条目。例如 -S proto -S res 等同于 -S res,proto，-S res:720,fps -S vcodec,res:1080 等同于 -S vcodec,res:1080,fps。你可以使用 --format-sort-reset 忽略之前传入的所有 -S/--format-sort 参数，并恢复为默认顺序。

提示：你可以使用 -v -F 查看格式的排序结果（从最差到最好）。

格式选择示例

# Download and merge the best video-only format and the best audio-only format,
# or download the best combined format if video-only format is not available
$ yt-dlp -f "bv+ba/b"

# Download best format that contains video,
# and if it doesn't already have an audio stream, merge it with best audio-only format
$ yt-dlp -f "bv*+ba/b"

# Same as above
$ yt-dlp

# Download the best video-only format and the best audio-only format without merging them
# For this case, an output template should be used since
# by default, bestvideo and bestaudio will have the same file name.
$ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"

# Download and merge the best format that has a video stream,
# and all audio-only formats into one file
$ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams

# Download and merge the best format that has a video stream,
# and the best 2 audio-only formats into one file
$ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams


# The following examples show the old method (without -S) of format selection
# and how to use -S to achieve a similar but (generally) better result

# Download the worst video available (old method)
$ yt-dlp -f "wv*+wa/w"

# Download the best video available but with the smallest resolution
$ yt-dlp -S "+res"

# Download the smallest video available
$ yt-dlp -S "+size,+br"



# Download the best mp4 video available, or the best video if no mp4 available
$ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"

# Download the best video with the best extension
# (For video, mp4 > mov > webm > flv. For audio, m4a > aac > mp3 ...)
$ yt-dlp -S "ext"



# Download the best video available but no better than 480p,
# or the worst video if there is no video under 480p
$ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"

# Download the best video available with the largest height but no better than 480p,
# or the best video with the smallest resolution if there is no video under 480p
$ yt-dlp -S "height:480"

# Download the best video available with the largest resolution but no better than 480p,
# or the best video with the smallest resolution if there is no video under 480p
# Resolution is determined by using the smallest dimension.
# So this works correctly for vertical videos as well
$ yt-dlp -S "res:480"



# Download the best video (that also has audio) but no bigger than 50 MB,
# or the worst video (that also has audio) if there is no video under 50 MB
$ yt-dlp -f "b[filesize<50M] / w"

# Download the largest video (that also has audio) but no bigger than 50 MB,
# or the smallest video (that also has audio) if there is no video under 50 MB
$ yt-dlp -f "b" -S "filesize:50M"

# Download the best video (that also has audio) that is closest in size to 50 MB
$ yt-dlp -f "b" -S "filesize~50M"



# Download best video available via direct link over HTTP/HTTPS protocol,
# or the best video available via any protocol if there is no such video
$ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"

# Download best video available via the best protocol
# (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
$ yt-dlp -S "proto"



# Download the best video with either h264 or h265 codec,
# or the best video if there is no such video
$ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"

# Download the best video with best codec no better than h264,
# or the best video with worst codec if there is no such video
$ yt-dlp -S "codec:h264"

# Download the best video with worst codec no worse than h264,
# or the best video with best codec if there is no such video
$ yt-dlp -S "+codec:h264"



# More complex examples

# Download the best video no better than 720p preferring framerate greater than 30,
# or the worst video (still preferring framerate greater than 30) if there is no such video
$ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"

# Download the video with the largest resolution no better than 720p,
# or the video with the smallest resolution available if there is no such video,
# preferring larger framerate for formats with the same resolution
$ yt-dlp -S "res:720,fps"



# Download the video with smallest resolution no worse than 480p,
# or the video with the largest resolution available if there is no such video,
# preferring better codec and then larger total bitrate for the same resolution
$ yt-dlp -S "+res:480,codec,br"

修改元数据

通过提取器获取的元数据可以使用 --parse-metadata 和 --replace-in-metadata 进行修改。

--replace-in-metadata FIELDS REGEX REPLACE 用于替换任意元数据字段中的文本，所用语法为 Python 正则表达式。替换字符串中可以使用反向引用，以实现更高级的用法。

--parse-metadata FROM:TO 的通用语法是：先给出要从中提取数据的字段名或输出模板，再给出解释该数据的格式，两者之间用冒号 : 分隔。TO 可以使用带命名捕获组的 Python 正则表达式、单个字段名，或与输出模板类似的语法（仅支持 %(field)s 格式）。该选项可以多次使用，以解析并修改多个字段。

注意：这些选项保持其相对顺序，因此既可以替换已解析字段中的内容，也可以反过来解析已替换的字段。此外，通过这些选项创建的任何字段都可以在输出模板中使用，并且会影响使用 --embed-metadata 时添加到媒体文件中的元数据。

该选项还有一些特殊用法：

  • 可以根据当前下载视频的元数据下载额外的 URL。为此，将字段 additional_urls 设置为要下载的 URL。例如，--parse-metadata "description:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" 会下载描述中找到的第一个 Vimeo 视频。

  • 可以用它修改嵌入媒体文件中的元数据。为此，为对应字段加上 meta_ 前缀并设置其值。例如，设置到 meta_description 字段的任何值都会被添加到文件的 description 字段中，你可以借此设置与"description"不同的"synopsis"。要修改单个流的元数据，请使用 meta<n>_ 前缀（例如 meta1_language）。设置到 meta_ 字段的任何值都会覆盖所有默认值。

注意：元数据修改发生在格式选择、提取后处理及其他后处理操作之前。某些字段可能会在这些步骤中被添加或更改，从而覆盖你的修改。

供参考，以下是 yt-dlp 默认添加到文件元数据中的字段：

元数据字段来源
titletrack 或 title
dateupload_date
description, synopsisdescription
purl, commentwebpage_url
tracktrack_number
artistartist、artists、creator、creators、uploader 或 uploader_id
composercomposer 或 composers
genregenre、genres、categories 或 tags
albumalbum 或 series
album_artistalbum_artist 或 album_artists
discdisc_number
showseries
season_numberseason_number
episode_idepisode 或 episode_id
episode_sortepisode_number
每个流的 language格式的 language

注意：文件格式可能不支持其中部分字段

修改元数据示例

# Interpret the title as "Artist - Title"
$ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"

# Regex example
$ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"

# Copy the episode field to the title field (with FROM and TO as single fields)
$ yt-dlp --parse-metadata "episode:title"

# Set title as "Series name S01E05"
$ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"

# Prioritize uploader as the "artist" field in video metadata
$ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --embed-metadata

# Set "comment" field in video metadata using description instead of webpage_url,
# handling multiple lines correctly
$ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --embed-metadata

# Do not set any "synopsis" in the video metadata
$ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"

# Remove "formats" field from the infojson by setting it to an empty string
$ yt-dlp --parse-metadata "video::(?P<formats>)" --write-info-json

# Replace all spaces and "_" in title and uploader with a `-`
$ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"

提取器参数

部分提取器接受额外参数，可以通过 --extractor-args KEY:ARGS 传递。ARGS 是以 ;（分号）分隔的字符串，格式为 ARG=VAL1,VAL2。例如：--extractor-args "youtube:player-client=tv,mweb;formats=incomplete" --extractor-args "twitter:api=syndication"

注意：在命令行中，ARG 可以用 - 代替 _；例如 youtube:player-client" 会变为 youtube:player_client"

以下提取器支持此功能：

youtube
  • lang: 优先使用此语言代码（区分大小写）的翻译元数据（title、description 等）。默认情况下优先使用视频的主要语言元数据，并回退到 en 翻译。支持的内容语言代码列表参见 youtube/_base.py。
  • skip：一个或多个 hls、dash 或 translated_subs，分别用于跳过提取 m3u8 清单、dash 清单和自动翻译字幕。
  • player_client：用于提取视频数据的客户端。当前可用的客户端有 web、web_safari、web_embedded、web_music、web_creator、mweb、ios、visionos、android、android_vr、tv、tv_downgraded、tv_samsung 和 tv_simply。默认使用 tv_samsung,visionos,web。如果没有可用的 JavaScript 运行时或引擎，则省略 web 和 tv_samsung。如果向 yt-dlp 传入了已登录的 Cookie，免费账户使用 web_embedded,tv_samsung,web，付费账户使用 web_creator,tv_samsung,web。向 music.youtube.com 的 URL 传入已登录 Cookie 时，会添加 web_music 客户端。对于年龄限制视频，会添加 web_embedded 客户端，但它只有在视频可嵌入时才偶尔能成功绕过年龄限制。如果 android_vr 或 visionos 无法访问某视频，可能会将 web_embedded 作为回退添加。如果需要完成年龄验证，会为年龄限制视频添加 web_creator 客户端。部分客户端（如 web_creator 和 web_music）需要 po_token 才能下载其格式。部分客户端（如 web_creator）只能在通过身份验证后工作。并非所有客户端都支持通过 Cookie 进行身份验证。你可以使用 default 表示默认客户端，或使用 all 表示全部客户端（不推荐）。在客户端名称前加上 - 可将其排除，例如 youtube:player_client=default,-web。
  • player_skip：跳过一些通常为稳定提取所需的网络请求。可选一个或多个值：configs（跳过客户端配置）、webpage（跳过初始网页）、js（跳过 JS 播放器）、initial_data（跳过初始数据/下一集请求）。这些选项可以减少所需请求数量或避免部分速率限制，但可能导致格式或元数据缺失等问题。详情参见 #860 和 #12826。
  • webpage_skip：跳过提取内嵌网页数据。可选一个或两个值：player_response、initial_data。这些选项仅用于测试，不会跳过任何网络请求。默认不跳过任何内容；但如果使用了 actual 以外的 player_js_version 值，则隐含 webpage_skip=player_response。
  • webpage_client：用于请求视频网页的客户端，可选 web（默认）或 web_safari。
  • player_params：用于播放器请求的 YouTube 播放器参数。将覆盖 yt-dlp 设置的任何默认参数。
  • player_js_variant：用于 n/sig 解密的播放器 JavaScript 变体。已知变体有：main、tcc、tce、es5、es6、es6_tcc、es6_tce、tv、tv_es6、phone、house。默认为 main，其他变体仅用于调试。可使用 actual 采用网站指定的变体。
  • player_js_version：用于 n/sig 解密的播放器 JavaScript 版本，格式为 signature_timestamp@hash（例如 20348@0004de42）。默认使用网站指定的版本，可通过 actual 选择。使用其他任何值都会隐含 webpage_skip=player_response。
  • comment_sort：top 或 new（默认），选择评论排序方式（由 YouTube 端执行）。
  • max_comments：限制收集的评论数量。为逗号分隔的整数列表，表示 max-comments,max-parents,max-replies,max-replies-per-thread,max-depth。默认为 all,all,all,all,all。
    • max-depth 值为 1 时，无论 max-replies 或 max-replies-per-thread 设为何值，都会丢弃所有回复。
    • 例如，all,all,1000,10,2 表示最多获取 1000 条回复，每个主题最多 10 条回复，且只获取 2 层深度（即顶层评论及其直接回复）。1000,all,100 表示最多获取 1000 条评论，回复总数最多 100 条。
  • formats：更改返回的格式类型。dashy（将 HTTP 转换为 DASH）、duplicate（内容相同但 URL 或协议不同；包含 dashy）、incomplete（无法完整下载，包括直播和直播结束后的 dash、直播结束后的 m3u8，以及未使用 --live-from-start 的直播自适应 https）、missing_pot（包含需要 PO Token 但缺少该 Token 的格式）。
  • innertube_host：所有 API 请求使用的 Innertube API 主机，例如 studio.youtube.com、youtubei.googleapis.com。注意，从某个子域名导出的 Cookie 无法用于其他子域名。
  • innertube_key：所有 API 请求使用的 Innertube API 密钥。默认不使用 API 密钥。
  • raise_incomplete_data：Incomplete Data Received 会抛出错误，而不是报告警告。
  • data_sync_id：覆盖 Innertube API 请求中使用的账户 Data Sync ID。如果使用的账户配置了 youtube:player_skip=webpage,configs 或 youtubetab:skip=webpage，可能需要此设置。
  • visitor_data：覆盖 Innertube API 请求中使用的 Visitor Data。应与 player_skip=webpage,configs 一起使用，且不传入 Cookie。注意：使用不当可能产生不良影响。如果需要使用浏览器中的会话，应改为传入 Cookie（其中包含 Visitor ID）。
  • po_token：要使用的 Proof of Origin（PO）Token。为逗号分隔的 PO Token 列表，格式为 CLIENT.CONTEXT+PO_TOKEN，例如 youtube:po_token=web.gvs+XXX,web.player=XXX,web_safari.gvs+YYY。Context 可以是 gvs（Google Video Server URL）、player（Innertube 播放器请求）或 subs（字幕）之一。
  • pot_trace：为 PO Token 获取启用调试日志。可选 true 或 false（默认）。
  • fetch_pot：从提供方获取 PO Token 的策略。可选值：always（无论客户端是否要求在给定 Context 中使用 PO Token，始终尝试获取）、never（从不获取 PO Token），或 auto（默认；仅当客户端要求在给定 Context 中使用时才获取 PO Token）。
  • jsc_trace：为 JS Challenge 获取启用调试日志。可选 true 或 false（默认）。
  • use_ad_playback_context：跳过前贴片广告，消除下载前的强制等待时间。向 yt-dlp 传入付费账户 Cookie 时请勿使用，否则会丢失付费格式。仅对 mweb 和 web_music 播放器客户端有效。可选 true 或 false（默认）。
youtube-ejs
  • jitless：以无 JIT 模式运行受支持的 JavaScript 引擎。支持的运行时为 deno、node 和 bun。以性能/速度为代价提供更好的安全性。请注意，node 和 bun 仍被视为不安全。可选值为 true 或 false（默认）
youtubepot-webpo
  • bind_to_visitor_id：是否使用 Visitor ID 而非 Visitor Data 来缓存 WebPO 令牌。可选值为 true（默认）或 false
youtubetab（YouTube 播放列表、频道、订阅源等）
  • skip：一个或多个以下值：webpage（跳过初始网页下载），authcheck（在未下载初始网页时，允许下载需要身份验证的播放列表。这可能导致意外行为，详见 #1122）
  • approximate_date：在 flat-playlist 中提取近似的 upload_date 和 timestamp。这可能导致基于日期的过滤器略有偏差
generic
  • fragment_query：若未提供值，则将 mpd/m3u8 清单 URL 中的任意查询参数传递到其分片；否则应用以 fragment_query=VALUE 给出的查询字符串。注意，若流带有 HLS AES-128 密钥，则查询参数也会传递给密钥 URI，除非传入了 key_query extractor-arg，或通过 hls_key extractor-arg 提供了外部密钥 URI。不适用于 ffmpeg
  • variant_query：若未提供值，则将主 m3u8 URL 的查询参数传递到其变体播放列表 URL；否则应用以 variant_query=VALUE 给出的查询字符串
  • key_query：若未提供值，则将主 m3u8 URL 的查询参数传递到其 HLS AES-128 解密密钥 URI；否则应用以 key_query=VALUE 给出的查询字符串。注意，若通过 hls_key extractor-arg 提供了密钥 URI，则此选项无效。不适用于 ffmpeg
  • hls_key：HLS AES-128 密钥 URI 或 密钥（十六进制），以及可选的 IV（十六进制），格式为 (URI|KEY)[,IV]；例如 generic:hls_key=ABCDEF1234567980,0xFEDCBA0987654321。传入其中任一值都会强制使用原生 HLS 下载器，并覆盖 m3u8 播放列表中的相应值
  • is_live：跳过直播 HLS 检测并手动设置 live_status。值为 false 时设为 not_live，其他任何值（或不提供值）都会设为 is_live
  • impersonate：在初始网页请求中尝试模拟的目标；例如 generic:impersonate=safari,chrome-110。使用 generic:impersonate 可模拟任意可用目标，使用 generic:impersonate=false 可禁用模拟（默认）
vikichannel
  • video_types：要下载的视频类型，一个或多个值：episodes、movies、clips、trailers
youtubewebarchive
  • check_all：以更多请求为代价尝试检查更多内容。一个或多个值：thumbnails、captures
gamejolt
  • comment_sort：hot（默认）、you（需要 Cookie）、top、new，选择评论排序模式（由 GameJolt 端决定）
hotstar
  • res：要忽略的分辨率，一个或多个值：sd、hd、fhd
  • vcodec：要忽略的视频编码，一个或多个值：h264、h265、dvh265
  • dr：要忽略的动态范围，一个或多个值：sdr、hdr10、dv
instagram
  • app_id：API 请求所用的 X-IG-App-ID 请求头的值。可以是实际的 ID 号码、ios 或 web（默认）
niconicochannelplus
  • max_comments：要提取的评论数量上限，默认为 120
tiktok
  • api_hostname：用于移动端 API 调用的主机名，例如 api22-normal-c-alisg.tiktokv.com
  • app_name：移动端 API 调用默认使用的应用名称，例如 trill
  • app_version：移动端 API 调用默认使用的应用版本，应与 manifest_app_version 一同设置，例如 34.1.2
  • manifest_app_version：移动端 API 调用默认使用的数字版本号，例如 2023401020
  • aid：移动端 API 调用默认使用的应用 ID，例如 1180
  • app_info：启用移动端 API 提取，并提供一个或多个格式为 <iid>/[app_name]/[app_version]/[manifest_app_version]/[aid] 的应用信息字符串，其中 iid 为唯一的应用安装 ID。iid 是唯一必填项，其他值及其 / 分隔符均可省略，例如 tiktok:app_info=1234567890123456789 或 tiktok:app_info=123,456/trill///1180,789//34.0.1/340001
  • device_id：启用移动端 API 提取，并指定用于移动端 API 调用的真实设备 ID。默认为随机生成的 19 位数字字符串
rokfinchannel
  • tab：要下载的标签页，可选值为 new、top、videos、podcasts、streams 或 stacks 之一
twitter
  • api：选择用于推文提取的 API，可选 graphql（默认）、legacy 或 syndication。登录后此选项无效
stacommu, wrestleuniverse
  • device_id：由网站分配的 UUID 值，用于对付费直播内容实施设备数量限制。可在浏览器本地存储中找到
twitch
  • client_id：随 GraphQL 请求发送的客户端 ID 值，例如 twitch:client_id=kimne78kx3ncx6brgo4mv6wki5h1ko
nhkradirulive (NHK らじる★らじる LIVE)
  • area：要提取的地区版本。有效地区为：sapporo、sendai、tokyo、nagoya、osaka、hiroshima、matsuyama、fukuoka。默认为 tokyo
nflplusreplay
  • type：要提取的比赛回放类型。有效类型为：full_game、full_game_spanish、condensed_game 和 all_22。可使用 all 提取所有可用的回放类型，这也是默认值
jiocinema
  • refresh_token：可传入浏览器本地存储中的 refreshToken UUID，以延长登录会话的有效期。此时用户名填写 token，密码填写浏览器本地存储中的 accessToken
jiosaavn
  • bitrate：要请求的音频比特率，可选一个或多个值：16、32、64、128、320。默认为 128,320
afreecatvlive
  • cdn：调用获取直播流 URL 的 API 时使用的一个或多个 CDN ID，例如 gcp_cdn、gs_cdn_pc_app、gs_cdn_mobile_web、gs_cdn_pc_web
soundcloud
  • formats：向 API 请求的格式，值的格式应为 {protocol}_{codec}，例如 hls_opus,http_aac。* 字符用作通配符，例如 *_mp3，也可单独传入以请求所有格式。已知的协议包括 http、hls 和 hls-aes；已知的编解码器包括 aac、opus 和 mp3。原始 download 格式始终会被提取。默认为 http_aac,hls_aac,http_opus,hls_opus,http_mp3,hls_mp3
orfon (orf:on)
  • prefer_segments_playlist：可用时优先选择节目片段播放列表，而非单个完整视频。如需单独的片段，请使用 --concat-playlist never --extractor-args "orfon:prefer_segments_playlist"
bilibili
  • prefer_multi_flv：对于仍提供旧版格式的较早视频，优先提取 flv 格式而非 mp4 格式
sonylivseries
  • sort_order：剧集提取时的排序顺序，可选 asc（升序，最早的在前）或 desc（降序，最新的在前）。默认为 asc
streaks
  • api_key：用于 X-Streaks-Api-Key 请求头的 API 密钥
tver
  • backend：用于提取的后端 API，可选 streaks（默认）或 brightcove（已弃用）
vimeo
  • client: 用于提取视频数据的客户端。目前可用的客户端为 android 和 web。只能使用一个客户端。默认使用 web 客户端，且仅在配合账户 Cookie 或登录凭据时可用。android 客户端仅可配合先前缓存的 OAuth 令牌使用。
  • original_format_policy: 尝试提取原始格式的策略。可选值为 always、never 或 auto。默认的 auto 策略会尽量避免超出 web 客户端的 API 速率限制，仅当 Vimeo 公开了视频的可下载性时才发起额外请求。
adn
  • profile_id: 用于下载视频的高级账户配置文件的数字 ID（默认值：1）
zan
  • split_angles: 将多视角流拆分为独立的视角格式。下载时会强制对视频流重新编码，且需要 ffmpeg。可选 true 或 false（默认）

Note: 这些选项将来可能会在不保证向后兼容的情况下被更改或移除

插件

请注意，所有插件都会被导入，即使未被调用；并且不会对插件代码执行任何检查。使用插件风险自负，且仅在信任其代码时使用！

插件类型（<type>）可以是 extractor 或 postprocessor。

  • Extractor 插件无需通过命令行启用，当输入的 URL 与之匹配时会自动调用。
  • Extractor 插件优先于内置提取器。
  • Postprocessor 插件可使用 --use-postprocessor NAME 调用。

插件从命名空间包 yt_dlp_plugins.extractor 和 yt_dlp_plugins.postprocessor 中加载。

换句话说，磁盘上的文件结构大致如下：

    yt_dlp_plugins/
        extractor/
            myplugin.py
        postprocessor/
            myplugin.py

yt-dlp 会在多个位置查找这些 yt_dlp_plugins 命名空间文件夹，并从所有位置加载插件。 将环境变量 YTDLP_NO_PLUGINS 设置为任意非空值，即可完全禁用插件加载。

参见已知插件合集

安装插件

插件可以通过多种方法安装到不同位置。

  1. 配置目录： 插件包（包含 yt_dlp_plugins 命名空间文件夹）可以放入以下标准配置位置：

    • 用户插件
      • ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plugins/（推荐用于 Linux/macOS）
      • ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
      • ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/（推荐用于 Windows）
      • ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
      • ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
      • ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/
    • 系统插件
      • /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
      • /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/

  2. 可执行文件位置：插件包同样可以安装在可执行文件所在位置下的 yt-dlp-plugins 目录中（推荐用于便携式安装）：

    • 二进制文件：当 <root-dir>/yt-dlp.exe 存在时，<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/
    • 源代码：当 <root-dir>/yt_dlp/__main__.py 存在时，<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/

  3. pip 及 PYTHONPATH 中的其他位置

    • 插件包可以使用 pip 安装和管理。示例请参阅 yt-dlp-sample-plugins。
      • 注意：通过 pip 安装的各插件包之间，插件文件的文件名必须唯一。
    • 系统会在 PYTHONPATH 中的任意路径下查找 yt_dlp_plugins 命名空间文件夹。
      • 注意：此规则不适用于 Pyinstaller 构建版本。

.zip、.egg 和 .whl 压缩包，只要其根目录包含 yt_dlp_plugins 命名空间文件夹，也同样被支持作为插件包。

  • 例如 ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip，其中 mypluginpkg.zip 包含 yt_dlp_plugins/<type>/myplugin.py

使用 --verbose 运行 yt-dlp，以检查插件是否已加载。

开发插件

请参阅 yt-dlp-sample-plugins 仓库获取插件包模板，并参阅 wiki 中的 Plugin Development 部分获取插件开发指南。

对于提取器和后处理器，系统会分别从每个文件中导入所有以 IE/PP 结尾的公开类。该机制遵循下划线前缀规则（例如 _MyBasePluginIE 为私有类），并遵守 __all__。同样，模块名以下划线为前缀即可将其排除（例如 _myplugin.py）。

要用某个内置提取器的子类替换它，请设置 plugin_name 类关键字参数（例如 class MyPluginIE(ABuiltInIE, plugin_name='myplugin') 会用 MyPluginIE 替换 ABuiltInIE）。由于该提取器会替代父类，你应通过上述任一方法将其设为私有，以避免被单独导入。

如果你是插件作者，请将 yt-dlp-plugins 添加为仓库的 topic，以便他人发现。

关于如何编写和测试提取器，请参阅开发者说明。

嵌入 YT-DLP

yt-dlp 力求成为一个良好的命令行程序，因此可以从任何编程语言中调用。

你的程序应避免解析常规 stdout，因为其输出在未来版本中可能会发生变化。相反，应使用 -J、--print、--progress-template、--exec 等选项，生成可稳定复现和解析的命令行输出。

在 Python 程序中，你可以通过更强大的方式嵌入 yt-dlp，如下所示：

from yt_dlp import YoutubeDL

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']
with YoutubeDL() as ydl:
    ydl.download(URLS)

你很可能需要使用各种选项。可用选项列表请参阅 yt_dlp/YoutubeDL.py，或在 Python 交互环境中运行 help(yt_dlp.YoutubeDL)。如果你已熟悉命令行用法，可以使用 devscripts/cli_to_api.py 将任意命令行开关转换为 YoutubeDL 参数。

提示：如果你要将代码从 youtube-dl 迁移到 yt-dlp，需要注意一点：我们不保证 YoutubeDL.extract_info 的返回值可被 JSON 序列化，甚至不保证它是字典。它类似字典，但如果你需要确保得到可序列化的字典，请像下方示例那样将其传入 YoutubeDL.sanitize_info。

嵌入示例

提取信息
import json
import yt_dlp

URL = 'https://www.youtube.com/watch?v=YE7VzlLtp-4'

# ℹ️ See help(yt_dlp.YoutubeDL) for a list of available options and public functions
ydl_opts = {}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info(URL, download=False)

    # ℹ️ ydl.sanitize_info makes the info json-serializable
    print(json.dumps(ydl.sanitize_info(info)))
使用 info-json 下载
import yt_dlp

INFO_FILE = 'path/to/video.info.json'

with yt_dlp.YoutubeDL() as ydl:
    error_code = ydl.download_with_info_file(INFO_FILE)

print('Some videos failed to download' if error_code
      else 'All videos successfully downloaded')
提取音频
import yt_dlp

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']

ydl_opts = {
    'format': 'm4a/bestaudio/best',
    # ℹ️ See help(yt_dlp.postprocessor) for a list of available Postprocessors and their arguments
    'postprocessors': [{  # Extract audio using ffmpeg
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'm4a',
    }]
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)
筛选视频
import yt_dlp

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']

def longer_than_a_minute(info, *, incomplete):
    """Download only videos longer than a minute (or with unknown duration)"""
    duration = info.get('duration')
    if duration and duration < 60:
        return 'The video is too short'

ydl_opts = {
    'match_filter': longer_than_a_minute,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)
添加日志记录器和进度钩子
import yt_dlp

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']

class MyLogger:
    def debug(self, msg):
        # For compatibility with youtube-dl, both debug and info are passed into debug
        # You can distinguish them by the prefix '[debug] '
        if msg.startswith('[debug] '):
            pass
        else:
            self.info(msg)

    def info(self, msg):
        pass

    def warning(self, msg):
        pass

    def error(self, msg):
        print(msg)


# ℹ️ See "progress_hooks" in help(yt_dlp.YoutubeDL)
def my_hook(d):
    if d['status'] == 'finished':
        print('Done downloading, now post-processing ...')


ydl_opts = {
    'logger': MyLogger(),
    'progress_hooks': [my_hook],
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)
添加自定义 PostProcessor
import yt_dlp

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']

# ℹ️ See help(yt_dlp.postprocessor.PostProcessor)
class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
    def run(self, info):
        self.to_screen('Doing stuff')
        return [], info


with yt_dlp.YoutubeDL() as ydl:
    # ℹ️ "when" can take any value in yt_dlp.utils.POSTPROCESS_WHEN
    ydl.add_post_processor(MyCustomPP(), when='pre_process')
    ydl.download(URLS)
使用自定义格式选择器
import yt_dlp

URLS = ['https://www.youtube.com/watch?v=YE7VzlLtp-4']

def format_selector(ctx):
    """ Select the best video and the best audio that won't result in an mkv.
    NOTE: This is just an example and does not handle all cases """

    # formats are already sorted worst to best
    formats = ctx.get('formats')[::-1]

    # acodec='none' means there is no audio
    best_video = next(f for f in formats
                      if f['vcodec'] != 'none' and f['acodec'] == 'none')

    # find compatible audio extension
    audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
    # vcodec='none' means there is no video
    best_audio = next(f for f in formats if (
        f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))

    # These are the minimum required fields for a merged format
    yield {
        'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
        'ext': best_video['ext'],
        'requested_formats': [best_video, best_audio],
        # Must be + separated list of protocols
        'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
    }


ydl_opts = {
    'format': format_selector,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)

与 YOUTUBE-DL 的变化

新功能

  • 从 yt-dlc@f9401f2 分支而来，并合并了 youtube-dl@a08f2b7（例外情况）

  • SponsorBlock 集成：你可以利用 SponsorBlock API 标记或移除 YouTube 视频中的赞助片段。

  • 格式排序：默认的格式排序选项已更改，现在会优先选择更高分辨率和更好的编解码器，而不再简单地选择码率更大的格式。此外，你现在可以使用 -S 指定排序顺序。这使得格式选择比单纯使用 --format 容易得多（示例）

  • 与 animelover1984/youtube-dl 合并：你可以获得 animelover1984/youtube-dl 的大部分功能和改进，包括 --write-comments、BiliBiliSearch、BilibiliChannel、在 mp4/ogg/opus 中嵌入缩略图、播放列表 infojson 等。详情请参阅 #31。

  • YouTube 改进：

    • 支持 Clips、Stories（ytstories:<channel UCID>）、搜索（包括筛选器）*、YouTube Music 搜索、频道内搜索、搜索前缀（ytsearch:）*、Mixes，以及 Feeds（:ytfav、:ytwatchlater、:ytsubs、:ythistory、:ytrec、:ytnotif）
    • 修复 基于 n-sig 的限速 *
    • 使用 --live-from-start 从头下载直播（实验性）
    • 频道 URL 会下载该频道的所有上传内容，包括 Shorts 和直播

  • 来自浏览器的 Cookie：可使用 --cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER] 自动从所有主流 Web 浏览器中提取 Cookie。

  • 下载时间范围：可使用 --download-sections 按时间戳或章节部分下载视频。

  • 按章节拆分视频：可使用 --split-chapters 将视频按章节拆分为多个文件。

  • 多线程分片下载: 并行下载 m3u8/mpd 视频的多个分片。使用 --concurrent-fragments（-N）选项设置所用的线程数

  • 新增与修复的提取器: 新增了许多提取器，并修复了大量现有提取器。请参阅 更新日志 或 支持的网站列表

  • 新的 MSO: Philo、Spectrum、SlingTV、Cablevision、RCN 等

  • 从清单中提取字幕: 可以从流媒体清单中提取字幕。详情请参阅 commit/be6202f

  • 多路径与输出模板: 您可以为不同类型的文件设置不同的输出模板和下载路径。还可以使用 --paths（-P）设置临时路径，用于存放中间文件

  • 可移植配置: 配置文件会自动从主目录和根目录加载。详情请参阅 CONFIGURATION

  • 输出模板改进: 输出模板现在支持日期时间格式化、数值偏移、对象遍历等。详情请参阅 输出模板。借助 --parse-metadata 和 --replace-in-metadata，还可以完成更高级的操作

  • 其他新选项: 新增了许多选项，例如 --alias、--print、--concat-playlist、--wait-for-video、--retry-sleep、--sleep-requests、--convert-thumbnails、--force-download-archive、--force-overwrites、--break-match-filters 等

  • 改进: --format/--match-filters 中支持正则表达式及其他运算符，支持多个 --postprocessor-args 和 --downloader-args，归档检查更快，提供更多格式选择选项，支持合并多个视频/音频，支持多个 --config-locations，支持在不同阶段使用 --exec 等

  • 插件: 提取器和后处理器可以从外部文件加载。详情请参阅 插件

  • 自更新: 可以使用 yt-dlp -U 更新发布版本，如有需要，还可以使用 --update-to 降级

  • 自动构建: 可以使用 --update-to nightly 和 --update-to master 获取每夜构建/master 构建版本

完整的更改列表请参阅 更新日志 或 提交记录

标有 * 的功能已向 youtube-dl 回移植

与默认行为的差异

yt-dlp 的部分默认选项与 youtube-dl 和 youtube-dlc 不同：

  • yt-dlp 仅支持 Python 3.11+，并会随着更多版本进入生命周期结束阶段而逐步移除对它们的支持；而 youtube-dl 仍支持 Python 2.6+ 和 3.2+

  • 某些选项已不再有效。详情请参阅已移除的选项

  • 不支持将 avconv 作为 ffmpeg 的替代品

  • yt-dlp 与 youtube-dl 存储配置文件的位置略有不同。正确位置列表请参阅配置

  • 默认输出模板为 %(title)s [%(id)s].%(ext)s。此更改并无实际必要。这项更改发生在 yt-dlp 公开发布之前，现在也没有计划将其改回 %(title)s-%(id)s.%(ext)s。不过，你可以使用 --compat-options filename

  • 默认格式排序与 youtube-dl 不同，优先选择更高分辨率和更好的编解码器，而非更高比特率。你可以使用 --format-sort 选项更改为任意排序顺序，也可以使用 --compat-options format-sort 来采用 youtube-dl 的排序顺序。旧版 yt-dlp 因 VP9 兼容性更广而优先选择它；你可以使用 --compat-options prefer-vp9-sort 恢复该格式排序偏好。这两个兼容选项不能同时使用

  • 默认格式选择器为 bv*+ba/b。这意味着，如果找到一个优于最佳纯视频格式的合并视频 + 音频格式，就会优先选择后者。使用 -f bv+ba/b 或 --compat-options format-spec 可恢复原行为

  • 与 youtube-dlc 不同，yt-dlp 默认不允许将多个音频/视频流合并到一个文件中（因为这与 -f bv*+ba 的使用相冲突）。如有需要，必须使用 --audio-multistreams 和 --video-multistreams 启用此功能。你也可以使用 --compat-options multistreams 同时启用两者

  • 默认启用 --no-abort-on-error。使用 --abort-on-error 或 --compat-options abort-on-error 可改为在发生错误时中止

  • 写入缩略图、描述或 infojson 等元数据文件时，如果有相同信息，也会为播放列表写入这些文件。使用 --no-write-playlist-metafiles 或 --compat-options no-playlist-metafiles 可停止写入这些文件

  • 使用 --add-metadata 时，除了与 --write-info-json 搭配写入元数据外，还会将 infojson 附加到 mkv 文件中。使用 --no-embed-info-json 或 --compat-options no-attach-info-json 可恢复原行为

  • 与 youtube-dl 相比，使用 --add-metadata 时，部分元数据会嵌入到不同字段中。最值得注意的是，comment 字段包含 webpage_url，而 synopsis 包含 description。你可以使用 --parse-metadata 按需修改，也可以使用 --compat-options embed-metadata 恢复原行为

  • 使用 --playlist-reverse 和 --playlist-items 等选项时，playlist_index 的行为有所不同。详情请参阅 #302。如果想保留旧行为，可以使用 --compat-options playlist-index

  • -F 的输出采用了新的格式。使用 --compat-options list-formats 可恢复原格式

  • 直播聊天（如果有）会被视为字幕。使用 --sub-langs all,-live_chat 可下载除直播聊天外的所有字幕。你也可以使用 --compat-options no-live-chat，阻止下载任何直播聊天/弹幕

  • YouTube 频道 URL 会下载该频道的所有上传内容。若要仅下载特定标签页中的视频，请传入该标签页的 URL。如果频道没有所请求的标签页，就会报错。此外，如果 /live URL 对应的频道没有直播视频，也会报错，而不会静默下载整个频道。你可以使用 --compat-options no-youtube-channel-redirect 恢复所有这些重定向行为

  • YouTube 播放列表中也会列出不可用的视频。使用 --compat-options no-youtube-unavailable-videos 可将其移除

  • 从 YouTube 提取的上传日期采用 UTC。

  • 如果使用 ffmpeg 作为下载器，在可能的情况下，格式下载和合并会在一个步骤中完成。使用 --compat-options no-direct-merge 可恢复原行为

  • 如果可行，mp4 中的缩略图嵌入会使用 mutagen。使用 --compat-options embed-thumbnail-atomicparsley 可强制改用 AtomicParsley

  • 默认情况下，infojson 中会移除文件名等部分内部元数据。使用 --no-clean-infojson 或 --compat-options no-clean-infojson 可恢复原行为

  • 同时使用 --embed-subs 和 --write-subs 时，字幕会写入磁盘，也会嵌入媒体文件。你也可以只使用 --embed-subs 来嵌入字幕，并自动删除单独的字幕文件。更多信息请参阅 #630 (comment)。使用 --compat-options no-keep-subs 可恢复原行为

  • 如果已安装，将使用 certifi 提供的 SSL 根证书。如果想使用系统证书（例如自签名证书），请使用 --compat-options no-certifi

  • yt-dlp 对文件名中无效字符的清理方式与 youtube-dl 不同，也更智能。你可以使用 --compat-options filename-sanitization 恢复 youtube-dl 的行为 *（目前尚未实现）yt-dlp 会尽可能将外部下载器的输出解析为标准进度输出。你可以使用 --compat-options no-external-downloader-progress 直接获取下载器输出

  • 2021.09.01 至 2022.11.11（含）期间的 yt-dlp 版本会将 --match-filters 应用于嵌套播放列表。这是 8f18ac 的意外副作用，现已在 d7b460 中修复。使用 --compat-options playlist-match-filter 可恢复此行为

  • 2021.11.10 至 2023.06.21（含）期间的 yt-dlp 版本会估算分片/清单格式的 filesize_approx 值。此功能是在 f2fe69 中为方便用户而添加的，但由于估算值可能极不准确，已在 0dff8e 中撤销。使用 --compat-options manifest-filesize-approx 可继续提取估算值

  • yt-dlp 使用 requests 等现代 HTTP 客户端后端。使用 --compat-options prefer-legacy-http-handler 可优先使用旧版 HTTP 处理程序（urllib）来处理标准 HTTP 请求。

  • 子模块 swfinterp、casefold 已移除。

  • 传入 --simulate（或调用 extract_info 并设置 download=False）不再改变默认格式选择。详情请参阅 #9843。

  • yt-dlp 默认不再将服务器修改时间应用于下载的文件。使用 --mtime 或 --compat-options mtime-by-default 可恢复原行为。 为方便使用，提供了一些 compat 选项别名：

  • --compat-options all：使用所有 compat 选项（请勿使用！）

  • --compat-options youtube-dl：等同于 --compat-options all,-multistreams,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort,-allow-unsafe-exec-expansion

  • --compat-options youtube-dlc：等同于 --compat-options all,-no-live-chat,-no-youtube-channel-redirect,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort,-allow-unsafe-exec-expansion

  • --compat-options 2021：等同于 --compat-options 2022,no-certifi,filename-sanitization

  • --compat-options 2022：等同于 --compat-options 2023,playlist-match-filter,no-external-downloader-progress,prefer-legacy-http-handler,manifest-filesize-approx

  • --compat-options 2023：等同于 --compat-options 2024,prefer-vp9-sort

  • --compat-options 2024：等同于 --compat-options 2025,mtime-by-default

  • --compat-options 2025：目前不做任何事情。可用于启用所有未来的 compat 选项

使用某个按年份命名的 compat 选项别名，会将 yt-dlp 的默认行为固定为该自然年 年底 时的行为。

以下 compat 选项会恢复安全补丁发布之前存在漏洞的行为：

  • --compat-options allow-unsafe-ext：允许下载任意扩展名的文件（包括不安全的扩展名）（GHSA-79w7-vh3h-8g4j）

    :warning: 仅在有效文件下载因扩展名被识别为不常见而被拒绝时使用

    此选项可能导致远程代码执行！ 建议改为提交一个 issue！

  • --compat-options allow-unsafe-exec-expansion：--exec 选项允许在其命令中使用输出模板语法；但出于安全原因，可用的转换被限制为 i/d（有符号十进制整数）、f（十进制浮点数）和 q（shell 转义）。yt-dlp 2021.04.11 至 2026.03.17（含）的版本未应用此限制。此选项会撤销该限制

    :warning: 此选项可能导致远程代码执行！ 对于任何字符串值，建议在 exec 命令模板中使用 %()q 转换。

已弃用的选项

以下是所有已弃用的选项，以及实现相同效果的当前替代方案

几乎冗余的选项

虽然这些选项与其新版本对应项几乎相同，但仍存在一些差异，因此它们并非完全冗余

-j, --dump-json                  --print "%()j"
-F, --list-formats               --print formats_table
--list-thumbnails                --print thumbnails_table --print playlist:thumbnails_table
--list-subs                      --print automatic_captions_table --print subtitles_table
冗余选项

虽然这些选项是冗余的，但由于使用方便，仍建议使用

--get-description                --print description
--get-duration                   --print duration_string
--get-filename                   --print filename
--get-format                     --print format
--get-id                         --print id
--get-thumbnail                  --print thumbnail
-e, --get-title                  --print title
-g, --get-url                    --print urls
--match-title REGEX              --match-filters "title ~= (?i)REGEX"
--reject-title REGEX             --match-filters "title !~= (?i)REGEX"
--min-views COUNT                --match-filters "view_count >=? COUNT"
--max-views COUNT                --match-filters "view_count <=? COUNT"
--break-on-reject                使用 --break-match-filters
--user-agent UA                  --add-headers "User-Agent:UA"
--referer URL                    --add-headers "Referer:URL"
--playlist-start NUMBER          -I NUMBER:
--playlist-end NUMBER            -I :NUMBER
--playlist-reverse               -I ::-1
--no-playlist-reverse            默认
--no-colors                      --color no_color
不推荐使用

虽然这些选项仍可用，但不推荐使用，因为有其他替代方案可以实现相同功能

--force-generic-extractor        --ies generic,default
--exec-before-download CMD       --exec "before_dl:CMD"
--no-exec-before-download        --no-exec
--all-formats                    -f all
--all-subs                       --sub-langs all --write-subs
--print-json                     -j --no-simulate
--autonumber-size NUMBER         使用字符串格式化，例如 %(autonumber)03d
--autonumber-start NUMBER        使用内部字段格式化，例如 %(autonumber+NUMBER)s
--id                             -o "%(id)s.%(ext)s"
--metadata-from-title FORMAT     --parse-metadata "%(title)s:FORMAT"
--hls-prefer-native              --downloader "m3u8:native"
--hls-prefer-ffmpeg              --downloader "m3u8:ffmpeg"
--list-formats-old               --compat-options list-formats (别名: --no-list-formats-as-table)
--list-formats-as-table          --compat-options -list-formats [默认]
--geo-bypass                     --xff "default"
--no-geo-bypass                  --xff "never"
--geo-bypass-country CODE        --xff CODE
--geo-bypass-ip-block IP_BLOCK   --xff IP_BLOCK
开发者选项

这些选项不面向终端用户

--test                           仅下载视频的一部分，用于测试提取器
--load-pages                     加载由 --write-pages 导出的页面
--allow-unplayable-formats       同时列出无法播放的格式
--no-allow-unplayable-formats    默认
旧别名

这些别名因各种原因已不再记录在文档中

--clean-infojson                 --clean-info-json
--force-write-download-archive   --force-write-archive
--no-clean-infojson              --no-clean-info-json
--no-split-tracks                --no-split-chapters
--no-write-srt                   --no-write-subs
--prefer-unsecure                --prefer-insecure
--rate-limit RATE                --limit-rate RATE
--split-tracks                   --split-chapters
--srt-lang LANGS                 --sub-langs LANGS
--trim-file-names LENGTH         --trim-filenames LENGTH
--write-srt                      --write-subs
--yes-overwrites                 --force-overwrites
Sponskrub 选项

为支持 --sponsorblock 选项，已移除对 SponSkrub 的支持

--sponskrub                      --sponsorblock-mark all
--no-sponskrub                   --no-sponsorblock
--sponskrub-cut                  --sponsorblock-remove all
--no-sponskrub-cut               --sponsorblock-remove -all
--sponskrub-force                不适用
--no-sponskrub-force             不适用
--sponskrub-location             不适用
--sponskrub-args                 不适用
不再支持

这些选项可能无法再按预期工作

--prefer-avconv                  yt-dlp 不正式支持 avconv（别名：--no-prefer-ffmpeg）
--prefer-ffmpeg                  默认值（别名：--no-prefer-avconv）
-C, --call-home                  未实现
--no-call-home                   默认值
--include-ads                    不再支持
--no-include-ads                 默认值
--write-annotations              目前没有受支持的网站提供注释
--no-write-annotations           默认值
--cn-verification-proxy URL      已移除，是 --geo-verification-proxy URL 的别名
--youtube-skip-dash-manifest     已移除，是 --extractor-args "youtube:skip=dash" 的别名（别名：--no-youtube-include-dash-manifest）
--youtube-skip-hls-manifest      已移除，是 --extractor-args "youtube:skip=hls" 的别名（别名：--no-youtube-include-hls-manifest）
--youtube-include-dash-manifest  默认值（别名：--no-youtube-skip-dash-manifest）
--youtube-include-hls-manifest   默认值（别名：--no-youtube-skip-hls-manifest）
--youtube-print-sig-code         已移除测试功能
--dump-user-agent                不再支持
--xattr-set-filesize             不再支持
--compat-options seperate-video-versions  已无必要
--compat-options no-youtube-prefer-utc-upload-date  不再支持
已移除

这些别名已被移除，之后可能会重新使用。请相应地更新脚本和配置文件

-A, --auto-number                -o "%(autonumber)s-%(id)s.%(ext)s"
-t, -l, --title, --literal       -o "%(title)s-%(id)s.%(ext)s"
--avconv-location                --ffmpeg-location
--dump-headers                   --print-traffic
--dump-intermediate-pages        --dump-pages

贡献

有关提交问题和为项目贡献代码的说明，请参阅 CONTRIBUTING.md

维基

如需了解更多信息，请参阅 Wiki

评论

支持 Markdown