Как обновить yt-dlp — все способы установки, nightly и почему это важно

Автор Команда Tunelio·Опубликовано 7 сент. 2026

yt-dlp ломается, когда YouTube меняет плеер, а YouTube меняет его каждые несколько недель. Актуальная версия исправляет больше ошибок «403», «bot check» и «unable to extract», чем любой флаг. Команда зависит от способа установки: yt-dlp -U для бинарника, pip install -U yt-dlp для pip, brew upgrade yt-dlp для Homebrew, winget upgrade yt-dlp для Windows. Детали, каналы и автоматизация ниже.

Сначала: как yt-dlp был установлен

yt-dlp --version          # например 2026.08.12 — даты, не semver
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 (рекомендуется, когда stable отстаёт)
yt-dlp --update-to stable      # вернуться
yt-dlp --update-to master      # самая свежая сборка из каждого коммита

Самообновление заменяет исполняемый файл на месте; на Linux/macOS файл должен быть доступен вам на запись (sudo только если ставили от root). Канал nightly — рекомендация мейнтейнеров, когда YouTube только что что-то изменил, а фикс уже слит, но ещё не в стабильном релизе.

pip / pipx

python3 -m pip install -U "yt-dlp[default]"       # stable + рекомендуемые extras (curl_cffi и т. д.)
python3 -m pip install -U --pre "yt-dlp[default]" # nightly pre-релизы
pipx upgrade yt-dlp                               # если ставили через pipx

yt-dlp -U не работает для pip-установок (он сам об этом сообщит). Используйте тот же интерпретатор, что запускает yt-dlp — python3 -m pip не даст обновить другой Python. Extra [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 следует за upstream близко; 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 — одного обновления yt-dlp мало, если нет Deno (или Node/Bun). ffmpeg нужен для слияния видео и аудио на 1080p+ и для конвертации аудио. Проверьте оба через 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 от бага в своём коде.

Почему старые сборки ломаются

JavaScript плеера YouTube вычисляет подпись и параметр «n», которые должна нести каждая медиа-ссылка. Когда плеер меняется, старый yt-dlp считает их неверно, и загрузки падают с 403 Forbidden, замедляются до нескольких КБ/с или теряют форматы. Эвристики бот-проверки и список доверенных клиентов плеера тоже движутся. Ничего из этого не исправить со своей стороны иначе как обновлением — поэтому мейнтейнеры просят актуальную версию прежде чем смотреть любой баг-репорт.

Если обновление не помогло

• Запустите yt-dlp -vU и прочитайте первые строки: версия, рантайм, ffmpeg и любые «WARNING» о недостающих компонентах.
• Убедитесь, что обновлённая копия — та, что в PATH (which yt-dlp).
• Затем пройдите руководство по 403 и по бот-проверке — после версии обычные подозреваемые: репутация IP, отсутствие PO-токенов и cookies.

Устали обновлять?

Если yt-dlp работает внутри продукта, каждое изменение YouTube превращается в срочное обновление. Хостинговый API поглощает эти изменения на своей стороне и держит один стабильный контракт: GET /create со ссылкой возвращает ссылку на скачивание. Tunelio — наш сервис, учитывайте это; новые аккаунты получают 100 бесплатных кредитов.

Источники

• README yt-dlp — Installation, раздел «Update», каналы --update-to.
• Wiki yt-dlp — FAQ по установке (пакеты дистрибутивов, pip vs бинарник).
• Релизы yt-dlp — SHA2-256SUMS для проверки загрузок.