yt-dlp使い方完全ガイド2026｜インストール・フォーマット選択・エラー対処・全オプション

yt-dlpはYouTubeを含む1,400以上のサイトに対応する、事実上の業界標準の動画・音声ダウンローダーだ。★160k超・Unlicenseの活発なOSSとして10年以上維持されている。本記事はインストール → 基本の使い方 → フォーマット選択（137/136/22の意味）→ エラー別の対処法 → プラットフォーム別コマンドという実用の流れで2026年版を総まとめした完全ガイドだ。「最高画質で落ちない」「Sign in to confirm you're not a botで止まる」といった典型的なつまずきも、エラー別トラブルシューティングの表で一気に解消できる。後半ではWhisper連携・CVE-2026-26331・CI運用まで、初学者から実運用エンジニアまで対応する。

この記事では音声・動画ダウンローダーOSS yt-dlpを解説します。AI時代の自動化ツール全体像についてはAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方をご覧ください。

yt-dlpとは：youtube-dlの後継として10年続くOSS

yt-dlpの起源は2020年ごろ、当時メンテナンスが停滞していたyoutube-dl／youtube-dlcのフォークとして始まった。今ではyoutube-dlを大きく超える機能・対応サイト数・更新頻度を持ち、業界標準と化している。

「動画ダウンローダー」という見た目に反して、内部はかなり複雑だ。各サイトの仕様変更（YouTubeのプレイヤー変更、TikTokのAPI変更など）に追従するため、1,400ものextractorが個別実装されており、毎週のように更新が入る。

2026年2月：CVE-2026-26331（CVSS 8.8）の修正

yt-dlpを業務利用しているチームにとって最も重要なニュースがCVE-2026-26331の修正だ。2026年2月24日に公開され、CVSS 8.8（High）。2023.06.21から2026.02.21未満のすべてのバージョンに影響する。

脆弱性の核心：subprocess.Popen(shell=True)

問題は--netrc-cmdオプションの実装にあった。netrcファイル（認証情報を保存するファイル）を動的に取得するため、subprocess.Popen(shell=True)でシェル経由で外部コマンドを実行していた。「machine」値の検証が不十分だったため、悪意あるURLからシェルコマンドを注入できる状態だった。

# 概念的に表すと、こんな実装だった（修正前）
def get_netrc_credentials(netrc_cmd, machine):
    cmd = netrc_cmd.replace('{}', machine)  # ← machineに任意文字列が入る
    output = subprocess.Popen(cmd, shell=True, ...)  # ← shell=Trueで注入成立

machineはURLから抽出される値で、攻撃者がURLを操作できれば任意のシェルコマンドが実行される。動画ダウンロードのつもりでシェルが返ってくる事態が発生し得た。

修正内容

2026.02.21では「machine」値を安全な文字集合に限定し、想定外の文字が混入した場合はエラーで停止するよう修正された。これにより--netrc-cmdを使う既存スクリプトもおおむね動作を継続できる。

該当ユーザーの確認

# 現在のyt-dlpバージョンを確認
yt-dlp --version

# 2026.02.21以降であることを確認、それ以前なら即時更新
pip install --upgrade yt-dlp
# あるいは バイナリ運用なら
yt-dlp -U

--netrc-cmdを使っていない場合でも、念のため最新版へ更新を推奨する。CI環境やDockerイメージで古いyt-dlpが固定されているケースが意外に多いため、再ビルドを確実に行う。最新の脆弱性管理思想はサプライチェーンセキュリティ完全ガイドも参照したい。

Python 3.10必須化：3.9以下を使うチームは要対応

2025年10月にPython 3.9がEOL（End of Life）を迎えたことに伴い、yt-dlpもPython 3.10以上を必須とした。3.9以下のシステムでは最新のyt-dlpが動かない。Ubuntu 22.04 LTSはPython 3.10がデフォルトなので問題ないが、CentOS 7やAmazon Linux 2の古い環境は対応が必要だ。

# Python バージョン確認
python3 --version

# 3.10未満ならpyenv等で並列インストール
pyenv install 3.12.7
pyenv local 3.12.7
pip install yt-dlp

CI環境ではDockerイメージをpython:3.12-slim等に固定することで安定運用できる。

インストールと基本コマンド

インストール方法

# Pythonでのインストール（推奨）
pip install yt-dlp

# Homebrew（Mac）
brew install yt-dlp

# Linuxディストリのパッケージマネージャ
sudo apt install yt-dlp   # Debian/Ubuntu

# Windows
winget install yt-dlp
# または
scoop install yt-dlp

最低限覚えるべきコマンド

# 単純なダウンロード（最高画質を自動選択）
yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ

# 音声のみmp3で取得（Whisper入力に便利）
yt-dlp -x --audio-format mp3 URL

# 解像度指定（1080p以下に制限）
yt-dlp -f "bv*[height<=1080]+ba/b" URL

# 字幕も自動ダウンロード（日本語）
yt-dlp --write-sub --sub-langs ja --convert-subs srt URL

# プレイリスト全部
yt-dlp --yes-playlist URL

# 並列ダウンロード（4本）
yt-dlp -N 4 URL

-xは音声抽出フラグで、ffmpegが必要だ。事前にインストールしておく。

# ffmpeg（macOS）
brew install ffmpeg

# Linux
sudo apt install ffmpeg

Windowsのwinget install yt-dlpはPATH設定まで自動で行うため、コマンドプロンプトを開き直せばすぐ使える。より隔離した環境で管理したいならpipx install yt-dlp、CIやサーバでは後述のDockerが再現性の面で有利だ。

yt-dlpコマンド早見表：よく使うオプション一覧

細かい解説に入る前に、日常的に使うオプションを1枚の表にまとめておく。困ったらまずここに戻ってくればいい。用途別に最頻出のものだけを厳選した。

出力テンプレート（-o）で使う%(title)sや%(id)sのような書式は、ファイル名を「チャンネル名／アップロード日／タイトル」のように自在に組み立てられる。以降のセクションで、これらを実際のユースケースに落とし込んでいく。

フォーマットを自在に選ぶ：-F／-fとフォーマットコード（137・136・22）の意味

「最高画質で落としたはずが音声が入っていない」「なぜか360pになる」——yt-dlpで最初につまずくのがフォーマット選択だ。ここを理解すれば、詰まりの大半は避けられる。

まず-F（大文字）で、そのURLに用意されている全フォーマットを一覧表示する。

# 利用可能なフォーマット一覧を表示
yt-dlp -F https://www.youtube.com/watch?v=VIDEO_ID

出力にはフォーマットID・拡張子・解像度・コーデック・ファイルサイズが並ぶ。YouTubeでよく登場する代表的なコードの意味を押さえておこう。

YouTubeは高画質になるほど映像と音声が別ストリーム（DASH配信）になる。1080p以上は137＋140のように「映像のみ＋音声のみ」を結合（マージ）する必要があり、ここでffmpegが実質必須になる。

# 映像137 + 音声140を明示指定して結合
yt-dlp -f "137+140" URL

# より実用的：1080p以下で最良の映像+最良の音声、ダメなら一体型
yt-dlp -f "bv*[height<=1080]+ba/b" URL

bv*はbestvideo、baはbestaudio、末尾の/bは「別ストリーム結合が無理なら一体型（best）にフォールバック」の意味だ。

エラー別トラブルシューティング：詰まったらまずここ

yt-dlpは対象サイトの仕様が日々変わるため、エラーは避けられない。頻出エラーと一次対処を表にまとめる。このセクションだけブックマークしておく価値がある。

不具合の体感8割は「更新」で直る。まずここから。

# バイナリ運用なら
yt-dlp -U
# pip運用なら
pip install --upgrade yt-dlp

「No supported JavaScript runtime」への対処（2026年の新エラー）

2026年、YouTubeの一部フォーマットはJavaScriptによる署名計算を要求するようになり、yt-dlpは外部JSランタイムを呼び出す設計に変わった。ランタイムが無いとNo supported JavaScript runtime could be foundが出る。Denoの導入が推奨される。

# macOS / Linux
curl -fsSL https://deno.land/install.sh | sh
# Homebrew
brew install deno
# Windows (winget)
winget install DenoLand.Deno

導入後はyt-dlpが自動でランタイムを検出する。特別なオプションは不要だ。

bot判定・403が消えないとき

# 1. ブラウザCookieを渡してログイン状態を引き継ぐ
yt-dlp --cookies-from-browser chrome URL

# 2. TLSフィンガープリントを偽装
yt-dlp --impersonate chrome URL

# 3. 冗長ログで原因を特定する
yt-dlp -v URL 2>&1 | head -40

プラットフォーム別・実践コマンド集

yt-dlpは1,400+サイトに対応するが、サイトごとに「効くオプション」が違う。主要プラットフォームの実践パターンをまとめる。

# Twitchの長時間VODから10分〜20分だけ取得
yt-dlp --download-sections "*10:00-20:00" TWITCH_VOD_URL

# X（Twitter）の動画をログイン状態で取得
yt-dlp --cookies-from-browser chrome "https://x.com/user/status/ID"

認証が必要な動画を取得する：cookies連携の実践

メンバー限定・ログイン必須の動画は、ブラウザのログイン状態（Cookie）をyt-dlpに渡すことで、自分が正規にアクセスできる範囲で取得できる。最も手軽なのが--cookies-from-browserだ。

# Chrome / Firefox / Brave / Edge / Safari から自動取得
yt-dlp --cookies-from-browser chrome URL
yt-dlp --cookies-from-browser firefox URL
yt-dlp --cookies-from-browser brave URL
yt-dlp --cookies-from-browser safari URL

# プロファイルを指定（複数アカウント運用時）
yt-dlp --cookies-from-browser "chrome:Profile 1" URL

うまくいかない場合は、拡張機能でエクスポートしたNetscape形式のcookies.txtを直接渡す方法もある。

yt-dlp --cookies cookies.txt URL

音声抽出・字幕・サムネイル・チャプターを埋め込む

動画そのものだけでなく、付随データを扱えるのがyt-dlpの強みだ。AI前処理でもSNS投稿でも頻出のパターンをまとめる。

音声抽出（mp3 / opus / flac）

# mp3で高音質抽出（0=最高品質）
yt-dlp -x --audio-format mp3 --audio-quality 0 URL

# 可逆圧縮flac（アーカイブ用途）
yt-dlp -x --audio-format flac URL

# 高効率opus（配信・音声認識向け）
yt-dlp -x --audio-format opus URL

-xは「映像を捨てて音声のみ」、--audio-formatが出力形式、--audio-quality 0が最高品質だ（いずれもffmpeg必須）。

字幕（手動字幕・自動字幕・SRT変換・埋め込み）

# 日本語字幕をSRTで保存（無ければ自動字幕）
yt-dlp --write-subs --write-auto-subs --sub-langs ja --convert-subs srt URL

# 字幕を動画ファイルに焼き込まず埋め込む（ソフトサブ）
yt-dlp --embed-subs --sub-langs ja URL

# 字幕だけ欲しい（動画はダウンロードしない）
yt-dlp --write-auto-subs --sub-langs en --skip-download URL

--write-auto-subsはYouTubeの自動生成字幕を取得する。Whisperに通す前の下書きテキストとしても使える。

サムネイル・チャプターの埋め込み

# サムネイル・チャプター・全メタデータを埋め込む
yt-dlp --embed-thumbnail --embed-chapters --embed-metadata URL

--embed-chaptersを付けると、動画プレイヤーのシークバーに章分割が表示される。ポッドキャスト・長尺講義のアーカイブに便利だ。

プレイリスト・チャンネル一括ダウンロードとアーカイブ運用

複数動画をまとめて扱うときは、範囲指定と「取得済みスキップ」を組み合わせると事故が減る。

# プレイリスト全体
yt-dlp --yes-playlist "PLAYLIST_URL"

# 3本目から10本目だけ
yt-dlp --playlist-items 3-10 "PLAYLIST_URL"

# 特定番号だけ（1・5・8本目）
yt-dlp --playlist-items 1,5,8 "PLAYLIST_URL"

# ランダム順で取得（レート制限回避に有効）
yt-dlp --playlist-random "PLAYLIST_URL"

大規模・長時間の取得では、途中で止まっても再開できるダウンロードアーカイブが必須だ。

# 成功したIDをarchive.txtに記録し、次回は未取得分のみ
yt-dlp --download-archive archive.txt --no-overwrites "CHANNEL_URL"

# チャンネル名フォルダ + アップロード日 + タイトルで整理
yt-dlp -o "%(channel)s/%(upload_date)s_%(title)s.%(ext)s" "CHANNEL_URL"

一度成功したIDはarchive.txtに追記され、再実行時はスキップされる。チャンネル全体を毎日差分取得するような運用の土台になる。

ダウンロードを高速化する：並列・aria2・レート制御

大量取得では「速度」と「BANされない穏やかさ」のバランスが重要だ。

# 断片を並列取得（HLS/DASHで効く）
yt-dlp --concurrent-fragments 8 URL

# 外部ダウンローダaria2cを使う（大幅高速化）
yt-dlp --downloader aria2c --downloader-args "aria2c:-x16 -k1M" URL

# 逆に穏やかに：レート制限+スリープでBAN回避
yt-dlp --limit-rate 2M --sleep-interval 5 --max-sleep-interval 15 URL

--concurrent-fragmentsは1本の動画を分割並列で取得する（サーバに優しく速い）。aria2c連携はさらに速いが、過度な並列はレート制限やBANを招くため、業務では--limit-rateとの併用が安全だ。

アップデートとバージョン運用：安定版・nightly・pipx

yt-dlpは「常に最新」が基本だが、導入方法によって更新コマンドが違う。

YouTubeの仕様変更直後など、安定版がまだ追いついていないときはnightlyが有効だ。

# nightlyチャンネルへ切り替え
yt-dlp --update-to nightly

# 安定版へ戻す
yt-dlp --update-to stable

GUI・ラッパーで使う：CLIが苦手でも

コマンドラインが苦手なら、yt-dlpをエンジンに使うGUI／ラッパーがある。

GUIは手軽な一方、細かいフォーマット制御やCI連携はCLIに分がある。用途で使い分けたい。当サイトではyt-dlpをGUIで包んだyouwee（yt-dlp AI GUI）も解説している。

Pythonから組み込む：ライブラリとしてのyt-dlp

yt-dlpはCLIだけでなくPythonライブラリとしても使える。AIパイプラインへ組み込むならこちらが柔軟だ。

from yt_dlp import YoutubeDL

opts = {
    "format": "bv*[height<=1080]+ba/b",
    "outtmpl": "%(id)s.%(ext)s",
    "writesubtitles": True,
    "subtitleslangs": ["ja"],
}

with YoutubeDL(opts) as ydl:
    info = ydl.extract_info(
        "https://www.youtube.com/watch?v=VIDEO_ID", download=True
    )
    print(info["title"], info["duration"])

extract_info(download=False)にすればメタデータだけ取得でき、トレンド分析やRAG準備に使える。ダウンロード失敗はyt_dlp.utils.DownloadErrorで捕捉するのが定石だ。

yt-dlp vs youtube-dl / pytube / gallery-dl：使い分け

「結局どれを使えばいい？」に一言で答えるなら、動画・音声はyt-dlp一択だ。ただし用途次第で併用する価値があるツールもある。

youtube-dlは本家だが更新が遅く、bot判定や仕様変更に弱い。pytubeはYouTube限定で軽いが対応が不安定になりがちだ。gallery-dlは「画像」に強く、yt-dlpとは役割が別（動画＝yt-dlp、画像＝gallery-dl）で、併用するのが定石になっている。

AIワークフローとの連携：5つのパターン

yt-dlpはAI×動画の文脈で「データ準備の前処理層」として2026年も依然中核を担う。具体的な連携パターンを5つ紹介する。

1. Whisper／WhisperLiveKitでの音声文字起こし

YouTube動画の音声を抽出してローカルWhisperで文字起こしするのが最もポピュラーな組み合わせだ。

# 音声をWAVで取得（Whisper最適形式）
yt-dlp -x --audio-format wav --audio-quality 0 \
  -o "audio.%(ext)s" \
  https://www.youtube.com/watch?v=VIDEO_ID

# WhisperLiveKitで文字起こし
wlk transcribe audio.wav --diarization

会議録画やWebinar公開動画を一括で議事録化する用途に向く。詳細手順はWhisperLiveKit完全解説を参照してほしい。

2. 動画チャプター情報を活用したRAG準備

YouTube動画には作者が付けたチャプター情報が含まれている。yt-dlpで構造化メタデータを取得し、ベクトルDBに投入できる。

# メタデータJSONとして取得
yt-dlp --write-info-json --skip-download \
  -o "%(channel)s/%(title)s" \
  https://www.youtube.com/playlist?list=PLAYLIST_ID

info.jsonにはタイトル・説明文・チャプター・タグ・コメント数までフラットに収まり、LLMのコンテキストとして利用しやすい。

3. SponsorBlock連携で広告区間を除去

長尺コンテンツのAI処理時、スポンサー区間を含めるとノイズになる。yt-dlpはSponsorBlockをネイティブ統合している。

# スポンサー区間を切り出して保存
yt-dlp --sponsorblock-mark sponsor,selfpromo \
  --sponsorblock-remove sponsor URL

「広告区間に該当する文字起こしが要約に混入する」問題を抑え、AI出力品質が上がる。

4. ffmpeg post-processorによるクリップ生成

yt-dlpは--postprocessor-argsでffmpeg連携が可能。動画ハイライトや短尺SNS投稿用のクリップを直接生成できる。

# 30秒〜1分のクリップを切り出し
yt-dlp --download-sections "*30-60" \
  -o "clip.%(ext)s" URL

# 解像度を1080x1920（縦動画）に変換
yt-dlp --postprocessor-args "ffmpeg:-vf scale=1080:1920" \
  -o "shorts.%(ext)s" URL

YouTube Shorts Pipelineのようなショート動画自動生成パイプラインの基盤として組み込める。

5. 大規模チャンネル分析

「特定チャンネルの全動画タイトル・再生数・コメント数」を一括取得し、トレンド分析やコンテンツ戦略立案に使う。

# 動画一覧をJSON Lines形式で出力
yt-dlp --flat-playlist -J \
  https://www.youtube.com/@channel-name/videos > channel.jsonl

# jqで再生数Top 20を抽出
jq -r '.entries | sort_by(-.view_count) | .[0:20] | .[] | "\(.view_count)\t\(.title)"' channel.jsonl

これだけで競合分析の素材が揃う。

アーキテクチャ：なぜ1400サイトに対応できるか

URL入力からExtractor（サイト固有のスクレイピング実装）が選択され、フォーマット解析→ダウンロード→ポスト処理という流れで動く。重要なのは、Cookie ManagerとImpersonationが組み込まれていることだ。

Cookieによる認証コンテンツ取得

# ブラウザのCookieを使ってログインコンテンツへアクセス
yt-dlp --cookies-from-browser chrome URL

# Firefoxのプロファイル指定
yt-dlp --cookies-from-browser firefox:profile_name URL

サブスクリプション動画やメンバー限定コンテンツの取得（自分が正規会員であれば）に使える。

Impersonation（TLSフィンガープリント偽装）

近年はcurl-cffiを使ったTLSフィンガープリント偽装機能を搭載。Cloudflareなどのbot対策をバイパスできる。

# Chrome 124として偽装
yt-dlp --impersonate chrome-124 URL

これにより従来「直近のyt-dlpはCloudflareで弾かれる」という頻発トラブルがほぼ解消した。

競合・代替ツールとの比較

OSSでCLI、AI連携、活発な更新を兼ね備えるのは事実上yt-dlp一択だ。GUI操作で完結したい場合は4K Video DownloaderやCobaltも選択肢になる。

実運用Tips：止まりやすいパターンと回避策

1. YouTubeの仕様変更でextractorが壊れる

YouTubeはプレイヤーやシグネチャ計算を頻繁に変える。古いyt-dlpを使っていると突然「Sign in to confirm you’re not a bot」のエラーが出る。月1回は最新版に更新するのが安全。

# CIでの自動更新
pip install --upgrade yt-dlp

2. レート制限への対策

並列ダウンロード過多はBANリスクが高い。--limit-rateと--sleep-intervalで穏やかに動かす。

yt-dlp --limit-rate 2M --sleep-interval 5 --max-sleep-interval 15 URL

3. 大規模プレイリストでの中断回復

# 取得済み動画はスキップ
yt-dlp --download-archive done.txt --no-overwrites URL_PLAYLIST

done.txtに成功したIDが記録され、次回実行時は未取得分のみ再開する。

プラグインシステム：機能を自分で拡張する

yt-dlpは独自のExtractorやPost-Processorをプラグインとして注入できる。サードパーティのextractor集や独自社内サービス向けの拡張に有効だ。

# プラグインの配置場所（Linux/macOS）
~/.config/yt-dlp/plugins/
~/.yt-dlp/plugins/

# Windowsの場合
%APPDATA%\yt-dlp\plugins\

社内動画プラットフォーム向けのextractorを書きたい場合は、yt_dlp_plugins/extractor/<name>.pyという構成で配置すれば自動ロードされる。

# 最小プラグイン例（yt_dlp_plugins/extractor/example.py）
from yt_dlp.extractor.common import InfoExtractor

class ExampleIE(InfoExtractor):
    _VALID_URL = r'https?://example\.com/video/(?P<id>\d+)'

    def _real_extract(self, url):
        video_id = self._match_id(url)
        webpage = self._download_webpage(url, video_id)
        return {
            'id': video_id,
            'title': self._html_extract_title(webpage),
            'url': self._html_search_regex(r'video_url="([^"]+)"', webpage, 'url'),
        }

このextractorパターンは1,400+の公式extractorも同じ構造で実装されており、習得すればyt-dlp本体へのコントリビューションも狙える。

CI/CDでのyt-dlp運用パターン

定期的に動画データを取得してAIパイプラインに流し込む場合、CI/CDでの運用を考えたい。

GitHub Actionsでの定期実行例

# .github/workflows/daily-fetch.yml
name: Daily Video Fetch
on:
  schedule:
    - cron: '0 3 * * *'   # 毎日12:00 JST
  workflow_dispatch:

jobs:
  fetch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - run: |
          pip install --upgrade yt-dlp
          yt-dlp --version
      - run: |
          yt-dlp \
            --download-archive done.txt \
            --no-overwrites \
            --write-info-json --skip-download \
            -o "data/%(id)s" \
            $
      - uses: actions/upload-artifact@v4
        with:
          name: video-metadata
          path: data/

--skip-downloadを付ければメタデータのみ取得でき、トレンド分析・新着検出に有効だ。

Dockerでの再現可能環境

# yt-dlp + ffmpeg を固定したDockerfile
FROM python:3.12-slim

RUN apt-get update && \
    apt-get install -y --no-install-recommends ffmpeg && \
    rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir yt-dlp==2026.04.10

WORKDIR /work
ENTRYPOINT ["yt-dlp"]

バージョン固定で運用するとExtractor仕様変更時の動作不整合を回避できる一方、CVE対応は手動更新が必要になる。月次でDockerイメージをリビルドするルーチンを組むのが安全だ。

まとめ：「yt-dlpを最新にする」を運用に組み込む

yt-dlpは便利すぎるあまり「あって当たり前」のツールになりがちだ。だがCVE-2026-26331のような脆弱性、YouTubeの仕様変更、Python EOLなどで、いつ動かなくなってもおかしくない。月1回の更新とCVEウォッチを習慣化することで、AI動画ワークフローの土台を安定させられる。AIエージェントが大量に動画データを必要とする時代、yt-dlpはますます価値を増す中核ツールであり続ける。

最初の一歩はpip install --upgrade yt-dlp。バージョンが2026.02.21以上になっていることを確認したら、本記事のAIワークフロー連携を試してみてほしい。

参照ソース

• yt-dlp/yt-dlp (GitHub) - 本体リポジトリ
• yt-dlp Releases - 全リリース履歴
• GHSA-g3gw-q23r-pgqm: yt-dlp arbitrary command injection - CVE-2026-26331の公式アドバイザリ
• CVE-2026-26331 (GitLab Advisory) - サードパーティ脆弱性データベース
• Supported Sites (yt-dlp) - 対応サイト1,400+の公式リスト
• SponsorBlock - 連携先プロジェクトの公式サイト