yt-dlp/yt-dlp

源码：https://github.com/yt-dlp/yt-dlp
YT-DLP 发布版本 PyPI 捐赠 Discord 支持的站点 许可证：Unlicense CI状态 提交历史 最后提交

yt-dlp 是一个功能丰富的命令行音视频下载器，支持数千个站点。该项目是 youtube-dl（https://github.com/ytdl-org/youtube-dl）的一个分支，基于已不再活跃的 youtube-dlc（https://github.com/blackjack4494/yt-dlc）。

• 安装
  • 详细指南（https://github.com/yt-dlp/yt-dlp/wiki/Installation）
  • 发布文件
  • 更新
  • 依赖项
  • 编译
• 使用与选项
  • 通用选项
  • 网络选项
  • 地理限制
  • 视频选择
  • 下载选项
  • 文件系统选项
  • 缩略图选项
  • 互联网快捷方式选项
  • 详细与模拟选项
  • 解决方法
  • 视频格式选项
  • 字幕选项
  • 认证选项
  • 后处理选项
  • SponsorBlock选项
  • 提取器选项
  • 预设别名
• 配置
  • 配置文件编码
  • 使用netrc认证
  • 关于环境变量的说明
• 输出模板
  • 输出模板示例
• 格式选择
  • 筛选格式
  • 排序格式
  • 格式选择示例
• 修改元数据
  • 修改元数据示例
• 提取器参数
• 插件
  • 安装插件
  • 开发插件
• 嵌入yt-dlp
  • 嵌入示例
• 与youtube-dl的差异
  • 新特性
  • 默认行为差异
  • 已弃用的选项
• 贡献指南
  • 提交Issue
  • 开发者指南
• WIKI（https://github.com/yt-dlp/yt-dlp/wiki）
• FAQ（https://github.com/yt-dlp/yt-dlp/wiki/FAQ）

安装

Windows（https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe）
Unix（https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp）
MacOS（https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos）
PyPI（https://pypi.org/project/yt-dlp）
源码压缩包（https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz）
其他变体
所有版本（https://github.com/yt-dlp/yt-dlp/releases）

你可以使用二进制文件、pip（https://pypi.org/project/yt-dlp）或第三方包管理器来安装 yt-dlp。详细指南请参见 wiki（https://github.com/yt-dlp/yt-dlp/wiki/Installation）

发布文件

推荐

替代方案

杂项

可用于验证 GPG 签名的公钥位于此处（https://github.com/yt-dlp/yt-dlp/blob/master/public.key）

用法示例：

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+（https://www.gnu.org/licenses/gpl-3.0.html）许可。
zipimport Unix 可执行文件（yt-dlp）包含来自 meriyah（https://github.com/meriyah/meriyah）的 ISC（https://github.com/meriyah/meriyah/blob/main/LICENSE.md）许可代码和来自 astring（https://github.com/davidbonnet/astring）的 MIT（https://github.com/davidbonnet/astring/blob/main/LICENSE）许可代码。更多详情请参见 THIRD_PARTY_LICENSES.txt。

Git 仓库、源码压缩包（yt-dlp.tar.gz）、PyPI 源码分发版以及 PyPI 构建分发版（wheel）仅包含 Unlicense 许可的代码。

注意：手册页、shell 补全（自动完成）文件等位于源码压缩包内（https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.tar.gz）

更新

如果你使用的是发布二进制文件，可以通过 yt-dlp -U 来更新。

如果你通过 pip（https://github.com/yt-dlp/yt-dlp/wiki/Installation#with-pip）安装，只需重新运行安装程序时使用的命令即可。

对于其他第三方包管理器，请参见 wiki（https://github.com/yt-dlp/yt-dlp/wiki/Installation#third-party-package-managers）或参考其文档。

目前二进制文件有三个发布频道：stable（稳定版）、nightly（每日构建版）和 master（主分支版）。

• stable 是默认频道，发布节奏（大致）每月一次。虽然它被命名为“稳定版”，因为其许多更改已由 nightly 或 master 频道的用户测试过，但最新的 stable 版本往往“过时”，容易因外部变化（例如网站改版导致 yt-dlp 失效）而出现问题。
• nightly 频道每天 UTC 时间接近午夜时发布代码更改的版本。该频道反映了项目的开发快照，是 yt-dlp 常规用户的推荐频道。 nightly 发布版可以从 yt-dlp/yt-dlp-nightly-builds（https://github.com/yt-dlp/yt-dlp-nightly-builds/releases）获取，也可以作为 yt-dlp PyPI 包的开发版本（可通过 pip 的 --pre 标志安装）获取。
• master 频道提供“金丝雀”版本，在每次推送到主分支后立即发布。该频道始终提供最新的修复和功能，但可能更容易出现错误或回归。master 发布版可从 yt-dlp/yt-dlp-master-builds（https://github.com/yt-dlp/yt-dlp-master-builds/releases）获取。

使用 --update/-U 时，发布二进制文件只会更新到其当前频道。可以使用 --update-to CHANNEL 切换到不同的频道（如果有较新版本）。也可以使用 --update-to [CHANNEL@]TAG 来升级或降级到某个频道的特定标签。还可以使用 --update-to （/）切换到另一个完全不同的仓库的频道。不过要注意更新到哪个仓库，因为不同仓库的二进制文件不经过验证。

用法示例：

• 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 版本：

# 从稳定版可执行文件/二进制文件更新到 nightly：
yt-dlp --update-to nightly
# 用 pip 安装 nightly：
python -m pip install -U --pre "yt-dlp[default]"

当运行的 yt-dlp 版本超过 90 天时，你会看到一条提示更新到最新版本的警告信息。可以通过在命令或配置文件中添加 --no-update 来禁用此警告。

依赖项

支持 Python 3.10+（CPython）和 3.11+（PyPy）。其他版本和实现可能无法正常工作或完全不能工作。虽然所有其他依赖项都是可选的，但强烈推荐使用 ffmpeg、ffprobe、yt-dlp-ejs 以及一个受支持的 JavaScript 运行时/引擎。

强烈推荐

• ffmpeg 和 ffprobe（https://www.ffmpeg.org）—— 必需用于合并分离的视频和音频文件，以及各种后处理任务。许可证取决于构建方式（https://www.ffmpeg.org/legal.html）。由于 ffmpeg 是非常重要的依赖，我们在 yt-dlp/FFmpeg-Builds（https://github.com/yt-dlp/FFmpeg-Builds）提供了自己的构建版本。过去曾对这些构建版本应用补丁以修复 yt-dlp 用户的常见问题，但目前我们的构建版本与上游 ffmpeg 相同。详情请参见 readme（https://github.com/yt-dlp/FFmpeg-Builds#patches-applied） 重要：你需要的是 ffmpeg 二进制文件，而不是同名的 Python 包（https://pypi.org/project/ffmpeg）

• yt-dlp-ejs（https://github.com/yt-dlp/ejs）—— 必需用于完整的 YouTube 支持。采用 Unlicense（https://github.com/yt-dlp/ejs/blob/main/LICENSE）许可，包含 MIT（https://github.com/davidbonnet/astring/blob/main/LICENSE）和 ISC（https://github.com/meriyah/meriyah/blob/main/LICENSE.md）组件。还需要一个 JavaScript 运行时/引擎，如 deno（https://deno.land）（推荐）、node.js（https://nodejs.org）、bun（https://bun.sh）或 QuickJS（https://bellard.org/quickjs/）来运行 yt-dlp-ejs。请参见 wiki（https://github.com/yt-dlp/yt-dlp/wiki/EJS）

网络

• certifi（https://github.com/certifi/python-certifi）*—— 提供 Mozilla 根证书包。采用 MPLv2（https://github.com/certifi/python-certifi/blob/master/LICENSE）许可
• brotli（https://github.com/google/brotli）* 或 brotlicffi（https://github.com/python-hyper/brotlicffi）—— Brotli（https://en.wikipedia.org/wiki/Brotli）内容编码支持。两者均采用 MIT 许可 [1]（https://github.com/google/brotli/blob/master/LICENSE）[2]（https://github.com/python-hyper/brotlicffi/blob/master/LICENSE）
• websockets（https://github.com/aaugustin/websockets）*—— 用于通过 WebSocket 下载。采用 BSD-3-Clause（https://github.com/aaugustin/websockets/blob/main/LICENSE）许可
• requests（https://github.com/psf/requests）*—— HTTP 库。用于 HTTPS 代理和持久连接支持。采用 Apache-2.0（https://github.com/psf/requests/blob/main/LICENSE）许可

模拟浏览器

以下提供对模拟浏览器请求的支持。某些使用 TLS 指纹识别的站点可能需要此功能。

• curl_cffi（https://github.com/lexiforest/curl_cffi）（推荐）—— curl-impersonate（https://github.com/lexiforest/curl-impersonate）的 Python 绑定。提供 Chrome、Edge 和 Safari 的模拟目标。采用 MIT（https://github.com/lexiforest/curl_cffi/blob/main/LICENSE）许可
  • 可以通过 curl-cffi 附加组件安装，例如 pip install "yt-dlp[default,curl-cffi]"
  • 目前包含在大多数构建版本中，除了 yt-dlp（Unix zipimport 二进制文件）和 yt-dlp_x86（Windows 32位）

元数据

• mutagen（https://github.com/quodlibet/mutagen）*—— 用于在某些格式中嵌入缩略图（--embed-thumbnail）。采用 GPLv2+（https://github.com/quodlibet/mutagen/blob/master/COPYING）许可
• AtomicParsley（https://github.com/wez/atomicparsley）—— 用于在 mp4/m4a 文件中嵌入缩略图（当 mutagen/ffmpeg 无法完成时）。采用 GPLv2+（https://github.com/wez/atomicparsley/blob/master/COPYING）许可
• xattr（https://github.com/xattr/xattr）、pyxattr（https://github.com/iustin/pyxattr）或 setfattr（http://savannah.nongnu.org/projects/attr）—— 用于在 Mac 上写入 xattr 元数据（--xattrs）。