如何更新 yt-dlp —— 每种安装方式、nightly 渠道，以及为什么这很重要

作者 Tunelio 团队·发布于 2026年9月7日

YouTube 一改播放器 yt-dlp 就会失效，而 YouTube 每隔几周就改一次。保持 yt-dlp 为最新，比任何参数都能修复更多 “403”、“bot check” 和 “unable to extract” 错误。命令取决于安装方式：二进制用 yt-dlp -U，pip 用 pip install -U yt-dlp，Homebrew 用 brew upgrade yt-dlp，Windows 用 winget upgrade yt-dlp。细节、渠道和自动化见下文。

第一步：弄清 yt-dlp 是怎么安装的

yt-dlp --version          # 例如 2026.08.12 —— 是日期，不是语义化版本
which yt-dlp              # /usr/local/bin → 二进制，~/.local/bin 或 venv → pip，/opt/homebrew → brew
pip show yt-dlp 2>/dev/null | head -2

版本号是日期。超过一个月就先更新，再排查其他问题。用错方式更新（例如在发行版软件包之上再用 pip）会留下两份副本，而旧的那份继续运行 —— 这是 “我更新了但还是失败” 最常见的原因。

按安装方式更新

官方二进制（Linux、macOS、Windows exe）

yt-dlp -U                      # 自更新到最新稳定版
yt-dlp --update-to nightly     # 切换到 nightly 渠道（稳定版滞后时推荐）
yt-dlp --update-to stable      # 切回
yt-dlp --update-to master      # 最前沿，每次提交都构建

自更新会原地替换可执行文件；在 Linux/macOS 上该文件必须对你可写（只有以 root 安装时才用 sudo）。当 YouTube 刚改了东西、修复已合并但尚未进入稳定版时，nightly 渠道是维护者推荐的选择。

pip / pipx

python3 -m pip install -U "yt-dlp[default]"       # 稳定版 + 推荐的额外依赖（curl_cffi 等）
python3 -m pip install -U --pre "yt-dlp[default]" # nightly 预发布版
pipx upgrade yt-dlp                               # 若用 pipx 安装

yt-dlp -U 对 pip 安装无效（它会明确告诉你）。请使用运行 yt-dlp 的那个解释器 —— python3 -m pip 可避免更新到另一个 Python。[default] 额外依赖会拉入 curl_cffi 等可选组件，用于浏览器伪装。

Homebrew（macOS/Linux）

brew update && brew upgrade yt-dlp

Windows：winget、scoop、choco

winget upgrade yt-dlp
scoop update yt-dlp
choco upgrade yt-dlp

Linux 发行版软件包（apt、dnf、pacman）

Debian/Ubuntu 和大多数发行版仓库提供的 yt-dlp 比上游落后数月，对 YouTube 来说这就等于坏了。要么卸载软件包改用官方二进制或 pip 版本，要么接受它经常失败。Arch 的软件包紧跟上游；Ubuntu 的不是。

sudo apt remove yt-dlp
sudo curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o /usr/local/bin/yt-dlp
sudo chmod a+rx /usr/local/bin/yt-dlp

Docker

# 不带缓存重建，让 pip 层重新解析最新版本
docker build --no-cache -t yt-dlp-image .
# 或在 Dockerfile 中显式固定：  pip install "yt-dlp[default]==2026.9.1"

容器把版本冻结在构建时，所以 “更新” 意味着重建。请把 ffmpeg 和 JavaScript 运行时（Deno）加进镜像；如今两者都是完整 YouTube 支持所必需的。

别忘了 JavaScript 运行时和 ffmpeg

自 2025 年起，yt-dlp 需要外部 JS 运行时来解决 YouTube 的签名挑战 —— 如果缺少 Deno（或 Node/Bun），只更新 yt-dlp 是不够的。合并 1080p 以上的视频与音频、转换音频都需要 ffmpeg。用 yt-dlp -v 检查两者：调试头部会列出找到的运行时和 ffmpeg。

自动化

# cron：每晚 04:00 更新（二进制安装）
0 4 * * * /usr/local/bin/yt-dlp -U >/var/log/yt-dlp-update.log 2>&1

# 在脚本中：先更新再运行
yt-dlp -U >/dev/null 2>&1 || true
yt-dlp "$URL"

对任何无人值守的任务，每晚更新都比凌晨三点的故障便宜。每次失败都记录版本号，这样才能分辨是 YouTube 变了还是你自己的代码有 bug。

旧构建为什么会失效

YouTube 播放器的 JavaScript 负责计算每个媒体 URL 必须携带的签名和 “n” 参数。播放器一变，旧版 yt-dlp 就算错，下载会以 403 Forbidden 失败、被限速到每秒几 KB，或彻底丢失格式。机器人检测启发式和受信任播放器客户端列表也在变动。这些都无法从你这边修复，只能更新 —— 所以维护者在查看任何 bug 报告前都要求使用当前版本。

如果更新没有解决问题

• 运行 yt-dlp -vU 并阅读开头几行：版本、运行时、ffmpeg，以及关于缺失组件的任何 “WARNING”。
• 确认更新后的副本就是 PATH 中的那个（which yt-dlp）。
• 然后依次查看 403 指南和机器人验证指南 —— 版本之后，常见嫌疑是 IP 信誉、缺少 PO token 和 cookies。

更新烦了？

如果 yt-dlp 运行在产品内部，YouTube 的每次变动都会变成紧急更新。托管 API 在服务端吸收这些变化，并保持一个稳定契约：带 URL 的 GET /create 返回下载链接。Tunelio 是我们自己的服务，请据此权衡；新账号可获得 100 个免费额度。

来源

• yt-dlp README —— 安装、“Update” 一节、--update-to 渠道。
• yt-dlp wiki —— 安装 FAQ（发行版软件包、pip 与二进制）。
• yt-dlp releases —— 用于校验下载的 SHA2-256SUMS。