yt-dlp 使用指南：从命令行下载视频到在 Python 里调用

yt-dlp 是当前维护最活跃的开源音视频下载器：GitHub 上 18.7 万 star、1.6 万 fork，Python 编写，Unlicense 许可，支持数千个网站，最近一次发布为 2026.08.19。它是 youtube-dl 家族目前事实上的主流继任者：上游维护放缓后，社区的更新与新版本都集中到了它这里。本文只讲一件事：从安装 yt-dlp 到把它嵌入你自己的程序，开发者常用到的每一步。

一、这个项目是什么

yt-dlp 是一个命令行程序，给它一个网页链接，它把对应平台的音视频下载到本地。项目 fork 自 youtube-dl（ytdl-org），并合并过另一个停止维护的分支 youtube-dlc（blackjack4494）。仓库采用日历版本号，版本号就是发布日期，如 2026.08.19；至今已累计 136 个 release。站点的页面结构一旦变化，负责解析它的提取器（extractor，即把页面里的可下载地址交给下载器的模块）会随之更新，这是项目长期可用的基础。

许可证：仓库本体与 PyPI 源码包为 Unlicense（公有领域），但打包好的二进制内含 GPLv3+ 的第三方代码，作为整体按 GPLv3+ 分发。

二、安装与更新

安装有三种方式，按场景选择：

  • 独立二进制：从 GitHub Releases 下载对应平台的单文件可执行程序（如 Windows 的 yt-dlp.exe），无需 Python 环境，适合直接使用。发行包覆盖 Windows（x64/ARM64/x86）、macOS、Linux（glibc/musl、x86_64/aarch64/armv7l）；
  • pip 安装：pip install -U yt-dlp，适合在已有 Python 环境的开发机上使用，升级用同一命令；
  • 系统包管理器：Homebrew、Scoop、Chocolatey、winget、APT 等均有打包。

用二进制时，yt-dlp -U 一条命令即可自更新。项目提供三个发布通道：stable（约每月一发）、nightly（代码有变动即发，README 说明这是官方推荐给常规用户的通道）、master（每次推送 master 即发，最新但可能有回归）。日常使用建议选 nightly，站点变更导致的下载失败往往在这个通道先行修复。

三、日常下载的三个高频动作

1. 精确选择画质与格式

默认行为是下载当前可用的最高画质。想精确控制用 -f：

yt-dlp -F "视频URL"          # 列出该视频所有可用格式
yt-dlp -f "bestvideo*+bestaudio/best" "视频URL"   # 最佳视频+最佳音轨合并
yt-dlp -f "ba[acodec^=mp3]/ba/b" -x --audio-format mp3 "视频URL"   # 转成 mp3

画质与码率之外，可以用格式排序 -S 按自己的优先级挑选，例如优先 H.264 编码和 AAC 音轨、其次分辨率：

yt-dlp -S "vcodec:h264,lang,quality,res,fps,hdr:12,acodec:aac" "视频URL"

2. 字幕与缩略图

yt-dlp --write-subs --write-auto-subs --sub-langs "en.*,zh.*" --sub-format srt "视频URL"
yt-dlp --write-thumbnail "视频URL"     # 同时写入视频封面

字幕语言支持正则匹配（如上例取所有英文、中文字幕），--list-subs 可以预览每个视频可用的字幕。程序内需要结构化下载信息时，用 yt-dlp -J "视频URL" 输出 JSON，而不是解析命令行的普通输出，后者随版本变动、不适合程序依赖。

3. 剪掉片内赞助与开场结尾段

通过集成 SponsorBlock API（sponsor.ajay.app），可以把视频里已标记的赞助、开场、结尾等段落直接去掉或标记为章节：

yt-dlp --sponsorblock-remove "sponsor,selfpromo" "视频URL"     # 直接剪掉
yt-dlp --sponsorblock-mark "intro,outro" "视频URL"             # 改为章节，保留原片

分类包括 sponsor、intro、outro、selfpromo、preview、filler、interaction、poi_highlight 等，可用 all,-preview 这类写法排除某个类别。

四、用配置文件固化常用参数

命令行参数可以写进配置文件，之后每次运行自动生效。查找顺序是：--config-locations 指定文件 → 程序同目录的 yt-dlp.conf（便携安装推荐）→ 家目录/XDG_CONFIG_HOME/%APPDATA% 下的用户配置 → 系统的 /etc/yt-dlp.conf。取第一个找到的生效。

把日常固定参数放进去，例如：

# 保存位置与文件名模板
-P ~/Videos
-o "%(title)s [%(id)s].%(ext)s"
# 默认行为
--write-thumbnail
--sub-langs "zh.*,en.*"
--sponsorblock-remove sponsor

输出模板（-o）支持元数据字段与格式化操作，%(title)s、%(id)s、%(upload_date>%Y-%m-%d)s 是常用写法；若字段为空可用 %(uploader|Unknown)s 兜底，避免文件名出现空段。

需要账号登录的站点，可以把凭证写进 ~/.netrc（每行 machine <提取器名> login <用户名> password <密码>），运行时加 --netrc，避免每次在命令行传用户名密码、也避免密码留在 shell 历史里。

五、扩展与嵌入：把它变成自己工具链的一环

插件：提取器和后处理器可以从外部文件加载，社区因此能够为个人站点或私有协议快速提供支持，无需改动主程序。

Python API：在程序里 pip install yt-dlp 后直接嵌入，最常用的两种调用：

import yt_dlp

# 只取元数据，不下载
with yt_dlp.YoutubeDL({"skip_download": True}) as ydl:
    info = ydl.extract_info("https://www.youtube.com/watch?v=YE7VzlLtp-4", download=False)
    print(yt_dlp.YoutubeDL.sanitize_info(info))

# 下载并提取音频
ydl_opts = {
    "format": "m4a/bestaudio/best",
    "postprocessors": [{"key": "FFmpegExtractAudio", "preferredcodec": "m4a"}],
}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(["https://www.youtube.com/watch?v=YE7VzlLtp-4"])

YoutubeDL 支持进度钩子（progress_hooks）、自定义 logger、match_filter 过滤时长过短的视频、自定义后处理器（PostProcessor）等，适合对接批处理脚本或服务化封装。

结论

开发者的标准用法可以概括为：用 nightly 通道保持更新、用 -f/-S 精确控制格式、用配置文件固化常用参数、用 Python API 把它接进自己的程序。一句话记住它：给一个链接，它就能把音视频拿回来——并且这件事在数千个站点上都成立。