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

yt-dlpはYouTubeを含む1,400以上のサイトに対応する動画・音声ダウンローダーだ。★181,560（2026-08-01実測）・Unlicense。youtube-dlのフォークとして2020年ごろに始まり、いまは対応サイト数も更新頻度も本家を大きく超えている。本記事はインストール → フォーマット選択 → エラー対処とアップデート → 用途別コマンド → 脆弱性 → 法律 → AI連携の順にまとめた2026年版のガイドだ。

AI時代の自動化ツール全体の比較はAI自動化ツール｜ノーコードからコードまで2026年版の比較と選び方にまとめてある。本記事はその中の「動画・音声を取り込む層」を扱う。

yt-dlpのインストールと基本コマンド

導入方法は4通り。どれで入れたかで更新コマンドが変わるので、最初に決めておく。

pip install yt-dlp          # Python（要3.10+）。隔離したいなら pipx install yt-dlp
brew install yt-dlp         # macOS / Linux
sudo apt install yt-dlp     # Debian / Ubuntu
winget install yt-dlp       # Windows（PATH まで自動設定。scoop install yt-dlp でも可）

# 音声抽出・結合・切り出しに使う ffmpeg（実質必須）
brew install ffmpeg         # macOS
sudo apt install ffmpeg     # Linux

Python 3.9以下では最新版が動かない（2025年10月のPython 3.9 EOLに合わせて3.10必須化）。CentOS 7やAmazon Linux 2の古い環境は、pyenvで3.10以上を並べて入れる。

python3 --version
pyenv install 3.12.7 && pyenv local 3.12.7 && pip install yt-dlp

日常的に使うオプションは次の表でほぼ足りる。

yt-dlpのフォーマット選択：137・136・22の意味

「最高画質のはずが音声が無い」「なぜか360pになる」は、ほぼフォーマット選択が原因だ。まず -F でそのURLに用意された形式を一覧する。

yt-dlp -F https://www.youtube.com/watch?v=VIDEO_ID

yt-dlp -f "137+140" URL                  # 映像137 + 音声140 を明示して結合
yt-dlp -f "bv*[height<=1080]+ba/b" URL   # 1080p以下の最良映像+最良音声、無理なら一体型

YouTubeは高画質になるほど映像と音声が別ストリーム（DASH配信）になる。bv* はbestvideo、ba はbestaudio、末尾の /b は「結合できなければ一体型にフォールバック」の意味だ。-f best は「一体型の中での最良」を選ぶため、DASHの1080p/4Kが候補から外れて720p止まりになることがある。

yt-dlpのエラー別対処とアップデート

対象サイトの仕様は日々変わるので、エラーは避けられない。不具合の体感8割は更新で直る。

2026年、YouTubeの一部フォーマットはJavaScriptによる署名計算を要求するようになり、yt-dlpは外部のJSランタイムを呼ぶ設計に変わった。Denoを入れれば自動で検出され、オプションは要らない。

# JSランタイム（Deno）
curl -fsSL https://deno.land/install.sh | sh   # macOS / Linux（brew install deno でも可）
winget install DenoLand.Deno                    # Windows

# bot判定・403が消えないとき
yt-dlp --cookies-from-browser chrome URL        # ログイン状態を引き継ぐ
yt-dlp --impersonate chrome URL                 # TLSフィンガープリントを偽装（curl-cffi）
yt-dlp -v URL 2>&1 | head -40                   # 冗長ログで原因を特定

入れ方ごとの更新コマンド

YouTubeの仕様変更直後で安定版が追いついていないときはnightlyが効く。

【実測】pipで入れたyt-dlpに -U を打つと

「更新＝yt-dlp -U」と覚えがちだが、pipで導入した場合 -U は更新しない。2026年8月26日、pipで古い版（2026.07.04）を入れて確かめた。

Current version: [email protected] from yt-dlp/yt-dlp
Latest version: [email protected] from yt-dlp/yt-dlp
ERROR: You installed yt-dlp with pip or using the wheel from PyPi; Use that to update

新しい版は検出しているのに自己更新は拒否する。終了コード100なのでcronやCIで失敗として拾えるが、yt-dlp -U | tee log のようにパイプに通すと $? はパイプ末尾の終了コードになり、100が消える。本稿でも最初この書き方で「0」と誤読しかけた。パイプを挟むなら PIPESTATUS（bash）／pipestatus（zsh）を見るか、ファイルへリダイレクトしてから $? を取る。

which -a yt-dlp                         # どこの yt-dlp が動いているか
pip show yt-dlp 2>/dev/null | head -3   # 出力があれば pip / pipx 管理

用途別コマンド：プラットフォーム・cookies・音声・一括取得

サイトごとに効くオプションが違う。主要プラットフォームの型は次のとおり。

メンバー限定・ログイン必須の動画は、ブラウザのCookieを渡せば自分が正規にアクセスできる範囲で取得できる。読めないときはブラウザを完全終了する（起動中はCookie DBがロックされる）。Chromeは近年Cookie暗号化が強化され、OSによってはキーチェーン許可が要る。不安定なら拡張機能で書き出したNetscape形式の cookies.txt を渡す。

yt-dlp --cookies-from-browser "chrome:Profile 1" URL   # chrome / firefox / brave / safari 等。プロファイル指定も可
yt-dlp --cookies cookies.txt URL                         # ファイル方式

# 音声・字幕・メタデータ
yt-dlp -x --audio-format mp3 --audio-quality 0 URL       # 0=最高品質。flac / opus も可
yt-dlp --write-subs --write-auto-subs --sub-langs ja --convert-subs srt URL
yt-dlp --embed-subs --sub-langs ja URL                   # 字幕をソフトサブで埋め込む
yt-dlp --embed-thumbnail --embed-chapters --embed-metadata URL

# プレイリスト・チャンネル
yt-dlp --playlist-items 3-10 "PLAYLIST_URL"              # 1,5,8 のような指定も可
yt-dlp --download-archive archive.txt --no-overwrites \
  -o "%(channel)s/%(upload_date)s_%(title)s.%(ext)s" "CHANNEL_URL"

# 速さと穏やかさ
yt-dlp --concurrent-fragments 8 URL                      # 断片を並列取得
yt-dlp --downloader aria2c --downloader-args "aria2c:-x16 -k1M" URL
yt-dlp --limit-rate 2M --sleep-interval 5 --max-sleep-interval 15 URL

--download-archive は成功したIDを追記し、次回は未取得分だけを取る。チャンネルを毎日差分取得する運用の土台になる。aria2c連携は速いが、過度な並列はレート制限やBANを招くので、業務では --limit-rate と併用する。--playlist-random で順番を散らすのもレート制限対策になる。

CLIが苦手なら、yt-dlpをエンジンにしたGUIもある（Stacher・Downie（有料）・ブラウザで使うcobalt・端末内のyt-dlp-tui）。細かいフォーマット制御やCI連携はCLIに分がある。当サイトではyt-dlpをGUIで包んだyouwee（yt-dlp AI GUI）も解説している。

yt-dlpの脆弱性：CVE-2026-26331とCVE-2026-55404

2026年は2件の脆弱性が修正された。どちらも該当オプションを使っていなければ直接の影響はないが、古い版を固定したCIやDockerイメージは意外に多い。

CVE-2026-55404の UI:R（ユーザー操作が必要）は、生成されたショートカットを開く一手を指す。

# 1. バージョンが 2026.07.04 以上か（2026.02.21 未満なら両方に該当）
yt-dlp --version

# 2. 過去のコマンド履歴に --write-link 系を使った形跡がないか
grep -rnE -- '--write-(link|url-link|desktop-link)' \
  ~/.bash_history ~/.zsh_history ./scripts 2>/dev/null

# 3. 手元のショートカットファイルの中身を検査する
find . -type f \( -name '*.url' -o -name '*.desktop' \) -print0 \
  | xargs -0 grep -nE '^(Exec|URL)=' 2>/dev/null

修正版 2026.07.04 のリリースノートには、環境要件の予告も2つ載っている。

・推奨されるPythonの最低バージョンが3.11に引き上げ。理由は「Python 3.10が2026年10月にEOLを迎えるため、まもなくサポートを打ち切る」
・公式のWindowsリリースバイナリは、まもなくWindows 10以降を要求する

3.10で運用している環境は、CVE対応の更新と同時に3.11以降への移行計画を立てておくと手戻りが少ない。CIやDockerで版を固定しているなら、再ビルドまでを対応に含める。

yt-dlpは違法か：ツールは合法、違法になるのは「何を落とすか」

yt-dlpはUnlicenseの公開ソフトウェアで、インストールも所持も日本の法律で禁じられていない。問題になるのは常に取得する対象と、権利者の許諾だ。

文化庁の解説によれば、令和2年の著作権法改正で「侵害コンテンツのダウンロード違法化」の対象が広がり、2021年1月1日に施行された。根拠は著作権法第30条第1項第4号・第2項、罰則は第119条第3項第2号など。

・違法にアップロードされた著作物と知りながらダウンロードする行為は、私的使用目的でも違法
・2021年改正で対象が音楽・映像から著作物全般（漫画・書籍・論文・プログラム等）へ広がった。音楽・映像はそれ以前（第30条第1項第3号）から対象
・権利者自身が公開している動画や、許諾のある配信の取得はこれに当たらない

著作権法とは別に利用規約がある。YouTubeの規約は、サービスが許可する場合（オフライン再生など）や権利者の書面許諾がある場合を除き、ダウンロードを禁じている。規約違反は刑事罰ではなく契約上の問題（アカウント停止など）だが、「著作権法に触れない＝規約上も自由」ではない。

本節は一次情報の所在を示すもので、個別の事案についての法的助言ではない。迷う用途は条文（e-Gov法令検索の著作権法）と文化庁の解説にあたるか、専門家に確認してほしい。

yt-dlpをAI・自動化に組み込む：Python・Whisper・CI

AI×動画の文脈で、yt-dlpは「データ準備の前処理層」を担う。Pythonライブラリとしても呼べる。

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) ならメタデータだけ取れる。失敗は yt_dlp.utils.DownloadError で捕まえる。

yt-dlp --flat-playlist -J https://www.youtube.com/@channel-name/videos > channel.jsonl
jq -r '.entries | sort_by(-.view_count) | .[0:20] | .[] | "\(.view_count)\t\(.title)"' channel.jsonl

定期実行するなら、GitHub Actions（python-version: '3.12'、cronで毎日）で pip install --upgrade yt-dlp してから --download-archive done.txt --no-overwrites --write-info-json --skip-download を回す形が組みやすい。再現性を取るならDockerで固定する。

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"]

版を固定すると仕様変更時の不整合は避けられる一方、CVE対応は手動になる。月1回はイメージを作り直すルーチンを組むのが安全だ。社内サービス向けには、~/.config/yt-dlp/plugins/（Windowsは %APPDATA%\yt-dlp\plugins\）に yt_dlp_plugins/extractor/<name>.py を置けば独自extractorが自動で読み込まれる。公式の1,400+のextractorも同じ InfoExtractor の構造で書かれている。

代替ツールとの使い分け

動画・音声ならyt-dlpが標準で、画像はgallery-dlと役割が分かれる（gallery-dlは内部にyt-dlpを呼ぶダウンローダーも持つ）。使い分けはgallery-dl使い方完全ガイド2026｜269サイト対応の画像一括ダウンロードをyt-dlpと使い分けるに実測つきでまとめた。yt-dlpが扱うのは尺が確定したファイルで、進行中のライブ配信の録画はStreamlink使い方ガイド2026｜135プラグインでライブ配信を録画するCLIをyt-dlpと使い分けるの守備範囲になる。

参照ソース

• 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 - 連携先プロジェクトの公式サイト