yt-dlp 使用指南 (中文版)

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

安装

Windows Unix MacOS PyPi 源代码压缩包 其他变体 所有版本

您可以使用二进制文件、pip 或第三方包管理器安装 yt-dlp。有关详细说明，请参阅 wiki。

发布文件

推荐

替代方案

(不推荐)

其他

可用于验证 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

注意：联机帮助页、shell 补全（自动完成）文件等可在源代码压缩包中找到。

更新

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

如果您使用 pip 安装，只需重新运行用于安装程序的相同命令。

对于其他第三方包管理器，请参阅 wiki 或参考其文档。

二进制文件目前有三个发布渠道：稳定版、夜间版和主线版。

• ​stable​ 是默认渠道，其许多更改已由 nightly​ 和 master​ 渠道的用户测试过。
• ​nightly​ 渠道每天大约在 UTC 午夜构建发布，以获取项目的最新补丁和更改的快照。这是推荐给 yt-dlp 常规用户的渠道。夜间版可从 yt-dlp/yt-dlp-nightly-builds 或作为 yt-dlp PyPI 包的开发版获取（可以使用 pip 的 --pre​ 标志安装）。
• ​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]​ 升级/降级到稳定版渠道标签 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

重要提示：任何遇到稳定版问题的用户应在提交错误报告之前安装或更新到夜间版：

# 从稳定版可执行文件/二进制文件更新到夜间版：
yt-dlp --update-to nightly

# 使用 pip 安装夜间版：
python3 -m pip install -U --pre "yt-dlp[default]"

依赖项

支持 Python 版本 3.8+（CPython 和 PyPy）。其他版本和实现可能无法正常工作。

虽然所有其他依赖项都是可选的，但强烈建议使用 ffmpeg 和 ffprobe。

强烈推荐

• ffmpeg 和 ffprobe - 合并单独的视频和音频文件以及各种后期处理任务所需。许可证取决于构建。

ffmpeg 中存在一些错误，与 yt-dlp 一起使用时会导致各种问题。由于 ffmpeg 是如此重要的依赖项，我们在 yt-dlp/FFmpeg-Builds 中提供了针对其中一些问题的补丁的自定义构建。有关这些构建解决的特定问题的详细信息，请参阅自述文件。

重要提示：您需要的是 ffmpeg 二进制文件，而不是同名的 Python 包。

网络

• certifi* - 提供 Mozilla 的根证书包。根据 MPLv2 授权。
• brotli* 或 brotlicffi - Brotli 内容编码支持。两者均根据 MIT 1 2 授权。
• websockets* - 用于通过 websocket 下载。根据 BSD-3-Clause 授权。
• requests* - HTTP 库。用于 HTTPS 代理和持久连接支持。根据 Apache-2.0 授权。

模拟

以下内容提供对模拟浏览器请求的支持。这对于某些使用 TLS 指纹识别的网站可能是必需的。

• curl_cffi（推荐） - 用于 curl-impersonate 的 Python 绑定。提供 Chrome、Edge 和 Safari 的模拟目标。根据 MIT 授权。 可以使用 curl-cffi 组安装，例如 pip install "yt-dlp[default,curl-cffi]"​ 目前仅包含在 yt-dlp.exe 和 yt-dlp_macos 构建中

元数据

• mutagen* - 用于某些格式的 --embed-thumbnail​。根据 GPLv2+ 授权。
• AtomicParsley - 当 mutagen/ffmpeg 无法使用时，用于 mp4/m4a 文件中的 --embed-thumbnail​。根据 GPLv2+ 授权。
• xattr、pyxattr 或 setfattr - 用于在 Mac 和 BSD 上写入 xattr 元数据 (--xattr​)。分别根据 MIT、LGPL2.1 和 GPLv2+ 授权。

其他

• pycryptodomex* - 用于解密 AES-128 HLS 流和各种其他数据。根据 BSD-2-Clause 授权。
• phantomjs - 用于需要运行 javascript 的提取器。根据 BSD-3-Clause 授权。
• secretstorage* - 用于 --cookies-from-browser​ 在 Linux 上解密基于 Chromium 的浏览器的 cookie 时访问 Gnome 密钥环。根据 BSD-3-Clause 授权。
• 任何您想与 --downloader​ 一起使用的外部下载器

已弃用

• avconv 和 avprobe - 现在已弃用，替代 ffmpeg。许可证取决于构建。
• sponskrub - 用于使用现已弃用的 sponskrub 选项。根据 GPLv3+ 授权。
• rtmpdump - 用于下载 rtmp 流。可以使用 ffmpeg 代替，并使用 --downloader ffmpeg​。根据 GPLv2+ 授权。
• mplayer 或 mpv - 用于下载 rstp/mms 流。可以使用 ffmpeg 代替，并使用 --downloader ffmpeg​。根据 GPLv2+ 授权。

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

独立的发布二进制文件是用 Python 解释器和包含*标记的包构建的。

如果您没有执行任务所需的必要依赖项，yt-dlp 将会警告您。所有当前可用的依赖项都显示在 --verbose​ 输出的顶部。

编译

独立的 PyInstaller 构建

要构建独立的可执行文件，您必须拥有 Python 和 pyinstaller（如果需要，还需要 yt-dlp 的任何可选依赖项）。可执行文件将针对与所使用的 Python 相同的 CPU 架构构建。

您可以运行以下命令：

python3 devscripts/install_deps.py --include pyinstaller
python3 devscripts/make_lazy_extractors.py
python3 -m bundle.pyinstaller

在某些系统上，您可能需要使用 py​ 或 python​ 代替 python3​。

​python -m bundle.pyinstaller​ 接受可以传递给 pyinstaller 的任何参数，例如 --onefile/-F​ 或 --onedir/-D​，这些参数在此处有详细说明。

注意：低于 4.4 的 Pyinstaller 版本不支持从 Windows 商店安装的 Python，除非使用虚拟环境。

重要提示：直接运行 pyinstaller 而不是使用 python -m bundle.pyinstaller​ 不受官方支持。这可能无法正常工作。

平台无关的二进制文件 (UNIX)

您将需要构建工具 python (3.8+)、zip、make (GNU)、pandoc* 和 pytest*。

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

您还可以运行 make yt-dlp​ 来仅编译二进制文件，而不更新任何其他文件。（这不需要*标记的构建工具）

独立的 Py2Exe 构建 (Windows)

虽然我们提供了使用 py2exe 构建的选项，但建议使用 PyInstaller 构建，因为 py2exe 构建不能包含 pycryptodomex/certifi，并且需要目标计算机上的 VC++14 才能运行。

如果您仍然希望构建它，请安装 Python（如果尚未安装），然后您可以运行以下命令：

py devscripts/install_deps.py --include py2exe
py devscripts/make_lazy_extractors.py
py -m bundle.py2exe

相关脚本

• ​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=1​。

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

Fork 项目

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

使用和选项

yt-dlp [选项] [--] 网址 [网址...]

Ctrl+F 是您的朋友