yt-dlp：開源視頻下載利器，從入門到精通

作者：道聽真說
日期：2026年2月8日 下午12:08
來源：WeChat 原文

✦整理版優先睇

速讀 5 個重點 高亮

yt-dlp係YouTube-dl嘅強力繼任者，活躍維護、功能豐富，支援數千個網站，係而家最值得用嘅開源視頻下載工具。

整理版摘要

呢篇文章係由一個開源愛好者整理，專門介紹yt-dlp呢個YouTube-dl嘅分支項目。作者想解決嘅問題係：YouTube-dl停咗維護之後，用戶需要一個更新快、支援更多網站同功能嘅替代品。整體結論係yt-dlp無論喺維護狀態、功能集、定係社區支援方面都明顯優勝，係而家視頻下載嘅首選。

文章詳細講咗yt-dlp嘅背景——由YouTube-dl分支出來，GitHub超過10.3萬Star；然後覆蓋咗安裝方法（pip、包管理器、二進制）、基本用法（下載單個視頻、音頻、指定格式）、字幕管理、高級格式選擇、批量下載、SponsorBlock集成、可視化界面，仲有最佳實踐同常見問題。成篇係實戰導向，逐個指令解釋，仲有配置樣板。

作者強調yt-dlp嘅核心優勢係活躍維護同功能豐富，支援YouTube、Bilibili、抖音、TikTok等數千個網站，可以同時處理下載、轉換、後期處理。對於成日要保存網上影片嘅用戶，呢篇可以話係一本通書。

  • yt-dlp係YouTube-dl嘅分支，GitHub超過103K Star，活躍維護，功能遠超原版。
  • 支援數千個網站，包括YouTube、Bilibili、抖音、TikTok等主流平台。
  • 基本用法好簡單：直接「yt-dlp URL」就下載最佳質量，或者用「-x」淨係抽音頻。
  • 進階功能有格式選擇器、批量下載、SponsorBlock自動跳廣告、配置文件省時。
  • 安裝強烈建議裝ffmpeg，否則冇得合併影片同音頻，亦做唔到格式轉換。
值得記低
連結 github.com

官方GitHub倉庫

yt-dlp主程式，有源碼、Release、Issue追蹤。

開啟
連結 github.com

官方文檔（README）

完整嘅使用說明、參數列表、安裝指引。

開啟
連結 github.com

支援網站列表

列出所有yt-dlp可以下載嘅網站。

開啟
連結 github.com

發佈版本

下載各平台嘅二進制檔案。

開啟
整理重點

點解要揀yt-dlp？背景同核心優勢

YouTube-dl曾經係視頻下載嘅王者，但因為版權問題喺2020年停咗維護。就喺呢個時候，yt-dlp作為分支誕生，而家GitHub超過10.3萬Star，變成主流。

同原版相比，yt-dlp支援嘅網站數由數百個增加到數千個，仲加入咗SponsorBlock集成、更強嘅格式選擇器、後期處理功能。兼容性方面，Windows、macOS、Linux全部支援，Windows 7都仲用得。

整理重點

安裝同基本設定：幾步搞掂

裝yt-dlp最簡單係用pip：python -m pip install -U "yt-dlp[default]"。如果你用macOS，可以brew install yt-dlp；Linux就用對應套件管理員。Windows用戶直接下載.exe擺喺PATH就得。

重點：一定要裝ffmpeg，否則冇辦法合併影片同音頻、做格式轉換或後期處理。安裝好之後，可以寫個配置文件，咁就唔使每次都打一大串參數。

配置文件範例（macOS/Linux: ~/.config/yt-dlp/config） plaintext 
-o ~/Downloads/%(title)s.%(ext)s
-f bestvideo+bestaudio
--write-subs
--embed-subs
--ignore-errors
整理重點

基本下載：由一條片到成個播放列表

最簡單嘅用法：yt-dlp https://www.youtube.com/watch?v=VIDEO_ID佢會自動揀最佳質量，如果網上有分離嘅影片同音頻，佢會各自下載再用ffmpeg合併。想淨係抽音頻，加-x參數，仲可以轉做MP3。

下載前先用yt-dlp -F URL睇下有咩格式，見到Format ID之後用-f 137+140呢類寫法指定。例如想下載1080p嘅MP4，就用-f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]"。

輸出文件名可以自訂，用-o加變量，例如%(uploader)s/%(title)s.%(ext)s。如果係播放列表，用--yes-playlist一次過下載，仲可以用--playlist-start/--playlist-end控制範圍。

整理重點

字幕同批量下載：節省時間嘅技巧

下載字幕可以用--write-subs，想揀語言就加--sub-langs "zh-Hans,en"。如果視頻本身冇字幕，試下--write-auto-subs攞YouTube自動生成嗰啲。想將字幕直接嵌埋入影片，用--embed-subs。

批量下載好簡單：將所有URL擺入一個txt檔案，然後用yt-dlp -a urls.txt。遇到錯誤可以用--ignore-errors</highlight>繼續，或者用--retries 5重試。

整理重點

進階功能：SponsorBlock、格式排序同GUI

yt-dlp內置咗SponsorBlock支援，可以自動跳過YouTube影片入面嘅贊助廣告、自我推廣、開場結尾等片段。用法係加--sponsorblock-remove參數，下載完嘅片就冇曬嗰啲位。

格式排序用-S參數，例如-S "res:1080,fps:30,codec:vp9"。另外，如果你唔喜歡命令行，社區做咗圖形界面，例如Parabolic（跨平台）、MeTube（Web界面啱NAS）、YT4KDownloader（專注4K）。

yt-dlp：開源影片下載利器，由入門到精通

YouTube-dl嘅強力接班人，GitHub 103K+ Stars，支援數千個網站

喺影片下載嘅世界入面，有一個名字好出名——YouTube-dl。但係隨住原項目停止維護，一個叫做yt-dlp嘅fork項目應運而生，唔單止繼承咗前者嘅所有優點，仲帶來咗好多改進同優化，喺GitHub上獲得咗超過10.3萬個Star，成為開源社羣嘅熱門項目。

📚 項目背景

由YouTube-dl到yt-dlp

YouTube-dl曾經係影片下載領域嘅王者，擁有超過13.4萬Star。但係因為法律同版權問題，呢個項目喺2020年停止咗維護。就喺呢個關鍵時刻，yt-dlp作為YouTube-dl嘅分支（fork）誕生咗。

圖片

點解要揀yt-dlp？

特性
YouTube-dl
yt-dlp
維護狀態
❌ 已停止
✅ 活躍更新
支援網站
數百個
數千個
功能特性
基本功能
豐富功能集
社羣支援
逐漸減少
持續增長
兼容性
Windows 7+
Windows 7+

yt-dlp嘅核心優勢係：

  1. 活躍嘅維護團隊：持續更新，及時修復問題，加入新功能
  2. 更豐富嘅功能：喺原有基礎上加咗大量新特性
  3. 更好嘅性能：優化下載速度，提升處理效率
  4. 更強嘅兼容性：支援更多網站同格式

✨ 核心功能特性

1. 跨平台支援

圖片

yt-dlp支援Windows、macOS同Linux三大主流操作系統：

  • Windows：提供.exe二進制檔案，支援Windows 7或以上版本
  • macOS：可以經Homebrew或者pip安裝
  • Linux：支援各大發行版，提供套件管理器同pip兩種安裝方式

2. 豐富嘅音影片格式

yt-dlp支援嘅格式種類好多：

  • 影片格式：MP4、WebM、MKV、AVI等
  • 音頻格式：MP3、M4A、OPUS、AAC等
  • 字幕格式：SRT、VTT、ASS等
  • 分辨率：由144p到4K甚至8K

3. 靈活嘅配置選項

yt-dlp提供咗豐富嘅命令列參數，幾乎可以控制下載嘅每個方面：

# 基礎參數
- h,--help # 顯示幫助
--version               # 顯示版本
- U, --update           # 更新到最新版本

# 下載控制
-i, --ignore-errors      # 忽略錯誤繼續下載
--abort-on-error        # 遇到錯誤停止

# 輸出控制
-o, --output           # 指定輸出路徑和文件名
--no-overwrites         # 不覆蓋已存在的文件
--continue              # 繼續未完成的下載

# 格式控制
-F, --list-formats      # 列出所有可用格式
-f, --format           # 選擇特定格式
-S, --format-sort       # 格式排序規則

4. 強大嘅後期處理功能

yt-dlp唔單止係下載工具，更加係一個完整嘅媒體處理管道：

  • 影片合併：自動合併分離咗嘅影片同音頻流
  • 格式轉換：將影片轉換做其他格式（需要ffmpeg）
  • 字幕嵌入：將字幕嵌入到影片檔案入面
  • 元數據注入：加入標題、描述、縮圖等元數據
  • 音頻提取：由影片中提取音頻檔案
圖片

5. SponsorBlock整合

yt-dlp整合咗SponsorBlock API，呢個係YouTube影片清理嘅神器：

  • 自動跳過贊助片段：識別並標記影片入面嘅廣告或贊助部分
  • 提升觀看體驗：去除幹擾內容，淨係睇核心內容
  • 可配置選項：可以選擇跳過、標記或保留贊助片段

🌐 支援嘅網站

yt-dlp支援數千個網站，涵蓋咗用戶日常使用嘅絕大多數平台：

主流影片平台

平台
支援情況
特殊說明
YouTube
✅ 完整支援
包括音樂頻道、直播、短影片等
Bilibili
✅ 完整支援
支援番劇、直播、彈幕
愛奇藝
✅ 完整支援
支援會員內容（需要cookies）
優酷
✅ 完整支援

TikTok
✅ 完整支援
支援用戶主頁下載
抖音
✅ 完整支援

其他平台

  • fc2（日本影片網站）
  • 芒果TV
  • Vimeo
  • Twitch
  • SoundCloud
  • Bandcamp
  • 同埋數千個其他網站

提示：睇完整支援列表，可以訪問項目嘅 supportedsites.md 文件。

📥 安裝同配置

方法一：用pip安裝（推薦）

呢個係最簡單、最通用嘅安裝方法：

# Python 3.7+
python -m pip install -U "yt-dlp[default]"

呢個指令會安裝yt-dlp同佢所有預設依賴項。

方法二：用套件管理器

# macOS Homebrew
brew install yt-dlp

# Linux (Ubuntu/Debian)
sudo apt install yt-dlp

# Linux (Arch)
sudo pacman -S yt-dlp

方法三：下載二進制檔案

對於Windows用戶，可以直接下載.exe檔案：

  1. 訪問 https://github.com/yt-dlp/yt-dlp/releases
  2. 下載最新嘅exe檔案
  3. 將檔案放喺系統PATH路徑入面

依賴配置

yt-dlp嘅某啲高級功能需要額外嘅依賴：

ffmpeg（強烈推薦）

ffmpeg係影片處理嘅核心工具，用嚟：

  • 合併音影片流
  • 格式轉換
  • 後期處理
# Windows
# 下載：https://www.gyan.dev/ffmpeg/builds/
# 解壓後添加到系統PATH

# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

設定檔

yt-dlp支援設定檔，避免每次都輸入長指令：

# macOS/Linux: ~/.config/yt-dlp/config
# Windows: %APPDATA%\yt-dlp\config.txt

設定檔示例：

# yt-dlp配置文件示例
-o ~/Downloads/%(title)s.%(ext)s
-f bestvideo+bestaudio
--write-subs
--embed-subs
--ignore-errors

🚀 基本使用教學

1. 下載單個影片

最簡單嘅用法，直接下載最佳質素嘅影片：

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

yt-dlp會：

  • 自動選擇最佳影片同音頻質素
  • 分別下載影片同音頻流
  • 使用ffmpeg自動合併
  • 保存為單個檔案

2. 下載音頻

如果你淨係需要音頻，例如下載音樂：

# 提取音頻，不下載視頻
yt-dlp -x https://www.youtube.com/watch?v=VIDEO_ID

# 提取音頻並轉換為MP3
yt-dlp -x --audio-format mp3 --audio-quality 0 https://www.youtube.com/watch?v=VIDEO_ID

參數說明：

  • -x 或 --extract-audio：提取音頻
  • --audio-format mp3：指定輸出格式做MP3
  • --audio-quality 0：0表示最佳質素

3. 睇可用格式

喺下載之前，先睇下有咩可選格式：

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

輸出示例：

[info] Available formats for VIDEO_ID:
ID  EXTRESOLUTIONFPS|FILESIZE|TBRPROTO|VCODEC ACODEC
137  mp41920x108030|~200MB|https|h264 none
248  webm1920x108060|~180MB|https|vp9 none
251  webmaudioonly-|2MB|https| -           opus
140  m4aaudioonly-|3MB|https| -           aac

列說明：

  • ID：格式代碼，用嚟指定下載
  • EXT：檔案副檔名
  • RESOLUTION：解析度
  • FPS：幀率
  • FILESIZE：預計檔案大小
  • TBR：位元率
  • VCODEC：影片編碼器
  • ACODEC：音頻編碼器

4. 下載指定格式

根據上面嘅格式列表，揀你想要嘅格式：

# 下載1080p視頻(mp4 137)和音頻(m4a 140)併合並
yt-dlp -f 137+140 https://www.youtube.com/watch?v=VIDEO_ID

# 使用格式選擇器
yt-dlp -f "bestvideo[height<=1080]+bestaudio" https://www.youtube.com/watch?v=VIDEO_ID

# 下載最佳質量MP4
yt-dlp -f "best[ext=mp4]" https://www.youtube.com/watch?v=VIDEO_ID

5. 自訂輸出路徑同檔案名

# 使用模板
yt-dlp -o "~/Videos/%(title)s.%(ext)s" https://www.youtube.com/watch?v=VIDEO_ID

# 使用日期
yt-dlp -o "%(uploader)s_%(upload_date)s_%(title)s.%(ext)s" URL

# 分級目錄
yt-dlp -o "Downloads/%(uploader)s/%(playlist_index)s-%(title)s.%(ext)s" URL

可用嘅模板變數：

變量
說明
示例
%(title)s
影片標題
"My Video"
%(uploader)s
上傳者
"John Doe"
%(upload_date)s
上傳日期
"20250207"
%(id)s
影片ID
"abc123"
%(ext)s
擴展名
"mp4"
%(height)s
影片高度
"1080"
%(width)s
影片寬度
"1920"

📝 字幕下載同管理

下載字幕

# 下載視頻的同時下載字幕
yt-dlp --write-subs https://www.youtube.com/watch?v=VIDEO_ID

淨係下載字幕，唔下載影片

yt-dlp --write-subs --skip-download https://www.youtube.com/watch?v=VIDEO_ID

睇可用字幕

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

輸出示例：

Available subtitles for VIDEO_ID:
Language Name Formats
en       English vtt, srt
zh-Hans  Chinese vtt, srt
zh-Hant  Chinese (Traditional) vtt, srt

下載指定語言嘅字幕

# 下載簡體中文字幕
yt-dlp --write-subs --sub-langs "zh-Hans" https://www.youtube.com/watch?v=VIDEO_ID

# 下載多種語言
yt-dlp --write-subs --sub-langs "en,zh-Hans" https://www.youtube.com/watch?v=VIDEO_ID

# 下載自動生成字幕
yt-dlp --write-auto-subs --sub-langs "zh-Hans" URL

嵌入字幕到影片

# 下載字幕並自動嵌入到視頻
yt-dlp --write-subs --embed-subs https://www.youtube.com/watch?v=VIDEO_ID

# 下載自動生成字幕並嵌入
yt-dlp --write-auto-subs --embed-subs URL

📊 高級格式選擇

格式選擇器

yt-dlp嘅格式選擇器好強大，可以精確控制下載嘅格式：

# 選擇最佳質量
yt-dlp -f "bestvideo+bestaudio"

# 限制最大分辨率
yt-dlp -f "bestvideo[height<=720]+bestaudio"

# 指定編碼器
yt-dlp -f "bestvideo[vcodet=vp9]+bestaudio"

# 組合條件
yt-dlp -f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]"

# 優先選擇
yt-dlp -f "bestvideo[height<=1080][fps<=30]+bestaudio/best"

格式排序

使用-S參數可以自訂格式排序優先級：

# 按分辨率排序（默認）
yt-dlp -S "res"

# 按文件大小排序
yt-dlp -S "filesize"

# 按幀率排序
yt-dlp -S "fps"

# 組合排序
yt-dlp -S "res:1080,fps:30,codec:vp9"

# 按比特率排序（越小越好）
yt-dlp -S "+tbr"

🔄 批量下載

從檔案批量下載

建立一個包含多個URL嘅文字檔案 urls.txt：

https://www.youtube.com/watch?v=VIDEO1
https://www.bilibili.com/video/BV1...
https://vimeo.com/123456

然後批量下載：

yt-dlp -a urls.txt

下載播放清單

# 下載整個播放列表
yt-dlp --yes-playlist https://www.youtube.com/playlist?list=PLAYLIST_ID

# 只下載播放列表的前5個視頻
yt-dlp --playlist-end 5 https://www.youtube.com/playlist?list=PLAYLIST_ID

# 從第3個開始下載
yt-dlp --playlist-start 3 https://www.youtube.com/playlist?list=PLAYLIST_ID

# 下載第5到第10個
yt-dlp --playlist-start 5 --playlist-end 10 URL

錯誤處理

喺批量下載時，遇到錯誤好常見：

# 忽略錯誤，繼續下載
yt-dlp --ignore-errors -a urls.txt

# 遇到錯誤停止
yt-dlp --abort-on-error -a urls.txt

# 重試指定次數
yt-dlp --retries 5 URL

# 使用緩存加速
yt-dlp --cache-dir /path/to/cache URL

🎯 SponsorBlock使用

咩係SponsorBlock？

SponsorBlock係一個開源嘅資料庫，記錄YouTube影片入面廣告同贊助片段嘅時間戳。用佢可以自動跳過呢啲內容。

啓用SponsorBlock

# 跳過贊助片段
yt-dlp --sponsorblock-mark https://www.youtube.com/watch?v=VIDEO_ID

# 下載時去除贊助部分
yt-dlp --sponsorblock-remove https://www.youtube.com/watch?v=VIDEO_ID

SponsorBlock分類

SponsorBlock可以識別嘅片段類型：

  • sponsor：贊助商廣告
  • selfpromo：自我推廣
  • interaction：訂閲同點讚提醒
  • intro：太長嘅開場白
  • outro：太長嘅結束
  • preview：下集預告
  • music_offtopic：音樂類非主題內容

📦 可視化界面同封裝

雖然yt-dlp係命令列工具，但社羣基於佢開發咗好多圖形化界面：

Parabolic

圖片
  • 特點：現代化界面，簡潔美觀
  • 支援：YouTube、Bilibili等1500+網站
  • 下載：影片、音頻、縮圖
  • 平台：Windows、macOS、Linux

MeTube

  • 特點：Web界面，適合NAS部署
  • 支援：播放清單批量下載
  • 功能：自動監控頻道更新
  • 部署：Docker一鍵部署

YT4KDownloader

  • 特點：專注於4K高質素下載
  • 支援：YouTube、Bilibili、Vimeo
  • 功能：字幕下載、元數據嵌入
  • 平台：Windows

Hitomi Downloader

  • 特點：功能強大嘅GUI工具
  • 支援：上千個網站
  • 功能：磁力、種子、批量下載
  • 特點：綠色免安裝

💡 最佳實踐

1. 先睇再下載

喺下載前，先用-F睇可用格式，揀最適合嘅：

# 查看格式
yt-dlp -F URL

# 選擇格式
yt-dlp -f 137+140 URL

2. 合理使用模板

設定檔入面使用輸出模板，令檔案管理更清晰：

# ~/config/yt-dlp/config
-o ~/Downloads/%(uploader)s/%(upload_date)s/%(title)s.%(ext)s
-f bestvideo+bestaudio
--write-subs
--embed-subs

3. 批量處理優化

# 使用限制併發
yt-dlp --concurrent-fragments 4 URL

# 使用緩存
yt-dlp --cache-dir ~/.cache/yt-dlp URL

# 使用代理加速
yt-dlp --proxy socks5://127.0.0.1:1080 URL

4. 錯誤處理

# 完整的錯誤處理命令
yt-dlp \
  --ignore-errors \
  --retries 5 \
  --fragment-retries 5 \
  --continue \
  --no-overwrites \
  URL

🔍 常見問題同解決方案

問題1：某啲網站無法下載

原因：網站更新咗反爬蟲機制

解決：

# 使用cookies
yt-dlp --cookies-from-browser firefox URL

# 使用user-agent
yt-dlp --user-agent "Mozilla/5.0..." URL

# 使用代理
yt-dlp --proxy http://127.0.0.1:8080 URL

問題2：下載速度慢

解決：

# 使用多線程下載片段
yt-dlp --concurrent-fragments 8 URL

# 指定多個源
yt-dlp --external-downloader aria2c URL

# 使用限速避免被封
yt-dlp --limit-rate 500K URL

問題3：ffmpeg相關錯誤

錯誤：ffmpeg not found或ffmpeg version too old

解決：

# 重新安裝最新版ffmpeg
brew reinstall ffmpeg  # macOS
sudo apt install ffmpeg  # Linux

# 驗證版本
ffmpeg -version

問題4：字幕下載失敗

原因：影片冇字幕或者字幕格式唔支援

解決：

# 先檢查是否有字幕
yt-dlp --list-subs URL

# 嘗試自動生成字幕
yt-dlp --write-auto-subs URL

--list-subs

問題5：合併失敗

錯誤：WARNING: ffmpeg not found

解決：

# 安裝ffmpeg
# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

# Windows
# 下載：https://www.gyan.dev/ffmpeg/builds/
# 添加到PATH

📊 yt-dlp vs 其他工具


📚 資源連結

  • 官方倉庫：https://github.com/yt-dlp/yt-dlp
  • 官方文檔：https://github.com/yt-dlp/yt-dlp/blob/master/README.md
  • 支援網站列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
  • 發佈版本：https://github.com/yt-dlp/yt-dlp/releases
  • Wiki文檔：https://github.com/yt-dlp/yt-dlp/wiki

總結

yt-dlp作為YouTube-dl嘅強力接班人，憑藉以下特點成為影片下載嘅首選工具：

  • ✅ 活躍維護：持續更新，及時修復問題
  • ✅ 功能豐富：下載、轉換、後期處理一站式解決
  • ✅ 支援廣泛：數千個網站，涵蓋主流平台
  • ✅ 靈活配置：豐富嘅命令列參數，滿足各種需求
  • ✅ 社羣活躍：103K+ Star，強大嘅社羣支援

無論係簡單嘅影片下載，定係複雜嘅批量處理同格式轉換，yt-dlp都可以輕鬆應對。掌握yt-dlp，令你嘅影片管理更加高效便捷！

"開源嘅力量，令每個人都擁有強大嘅工具。"

開始用yt-dlp，體驗開源影片下載嘅強大魅力！



yt-dlp：開源視頻下載利器，從入門到精通

YouTube-dl的強力繼任者，GitHub 103K+ Stars，支持數千個網站

在視頻下載的世界裏，有一個名字如雷貫耳——YouTube-dl。但隨着原項目停止維護，一個名為yt-dlp的fork項目應運而生，不僅繼承了前者的所有優點，還帶來了諸多改進和優化，在GitHub上斬獲了超過10.3萬個Star，成為開源社區的熱門項目。

📚 項目背景

從YouTube-dl到yt-dlp

YouTube-dl曾經是視頻下載領域的王者，擁有超過13.4萬Star。但由於法律和版權問題，該項目在2020年停止了維護。就在這個關鍵時刻，yt-dlp作為YouTube-dl的分支（fork）誕生了。

圖片

為什麼選擇yt-dlp？

特性
YouTube-dl
yt-dlp
維護狀態
❌ 已停止
✅ 活躍更新
支持網站
數百個
數千個
功能特性
基礎功能
豐富功能集
社區支持
逐漸減少
持續增長
兼容性
Windows 7+
Windows 7+

yt-dlp的核心優勢在於：

  1. 活躍的維護團隊：持續更新，及時修復問題，添加新功能
  2. 更豐富的功能：在原有基礎上增加了大量新特性
  3. 更好的性能：優化下載速度，提升處理效率
  4. 更強的兼容性：支持更多網站和格式

✨ 核心功能特性

1. 跨平台支持

圖片

yt-dlp支持Windows、macOS和Linux三大主流操作系統：

  • Windows：提供.exe二進制文件，支持Windows 7及以上版本
  • macOS：可通過Homebrew或pip安裝
  • Linux：支持各大發行版，提供包管理器和pip兩種安裝方式

2. 豐富的音視頻格式

yt-dlp支持的格式種類繁多：

  • 視頻格式：MP4、WebM、MKV、AVI等
  • 音頻格式：MP3、M4A、OPUS、AAC等
  • 字幕格式：SRT、VTT、ASS等
  • 分辨率：從144p到4K甚至8K

3. 靈活的配置選項

yt-dlp提供了豐富的命令行參數，幾乎可以控制下載的每個方面：

# 基礎參數
- h,--help # 顯示幫助
--version               # 顯示版本
- U, --update           # 更新到最新版本

# 下載控制
-i, --ignore-errors      # 忽略錯誤繼續下載
--abort-on-error        # 遇到錯誤停止

# 輸出控制
-o, --output           # 指定輸出路徑和文件名
--no-overwrites         # 不覆蓋已存在的文件
--continue              # 繼續未完成的下載

# 格式控制
-F, --list-formats      # 列出所有可用格式
-f, --format           # 選擇特定格式
-S, --format-sort       # 格式排序規則

4. 強大的後期處理功能

yt-dlp不僅僅是下載工具，更是一個完整的媒體處理管道：

  • 視頻合併：自動合併分離的視頻和音頻流
  • 格式轉換：將視頻轉換為其他格式（需要ffmpeg）
  • 字幕嵌入：將字幕嵌入到視頻文件中
  • 元數據注入：添加標題、描述、縮略圖等元數據
  • 音頻提取：從視頻中提取音頻文件
圖片

5. SponsorBlock集成

yt-dlp集成了SponsorBlock API，這是YouTube視頻清理的神器：

  • 自動跳過贊助片段：識別並標記視頻中的廣告或贊助部分
  • 提升觀看體驗：去除干擾內容，只看核心內容
  • 可配置選項：可選擇跳過、標記或保留贊助片段

🌐 支持的網站

yt-dlp支持數千個網站，涵蓋了用戶日常使用的絕大多數平台：

主流視頻平台

平台
支持情況
特殊說明
YouTube
✅ 完整支持
包括音樂頻道、直播、短視頻等
Bilibili
✅ 完整支持
支持番劇、直播、彈幕
愛奇藝
✅ 完整支持
支持會員內容（需cookies）
優酷
✅ 完整支持

TikTok
✅ 完整支持
支持用戶主頁下載
抖音
✅ 完整支持

其他平台

  • fc2（日本視頻網站）
  • 芒果TV
  • Vimeo
  • Twitch
  • SoundCloud
  • Bandcamp
  • 以及數千個其他網站

提示：查看完整支持列表，可以訪問項目的 supportedsites.md 文件。

📥 安裝與配置

方法一：使用pip安裝（推薦）

這是最簡單、最通用的安裝方法：

# Python 3.7+
python -m pip install -U "yt-dlp[default]"

這個命令會安裝yt-dlp及其所有默認依賴項。

方法二：使用包管理器

# macOS Homebrew
brew install yt-dlp

# Linux (Ubuntu/Debian)
sudo apt install yt-dlp

# Linux (Arch)
sudo pacman -S yt-dlp

方法三：下載二進制文件

對於Windows用戶，可以直接下載.exe文件：

  1. 訪問 https://github.com/yt-dlp/yt-dlp/releases
  2. 下載最新的exe文件
  3. 將文件放到系統PATH路徑中

依賴配置

yt-dlp的某些高級功能需要額外的依賴：

ffmpeg（強烈推薦）

ffmpeg是視頻處理的核心工具，用於：

  • 合併音視頻流
  • 格式轉換
  • 後期處理
# Windows
# 下載：https://www.gyan.dev/ffmpeg/builds/
# 解壓後添加到系統PATH

# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

配置文件

yt-dlp支持配置文件，避免每次都輸入長命令：

# macOS/Linux: ~/.config/yt-dlp/config
# Windows: %APPDATA%\yt-dlp\config.txt

配置文件示例：

# yt-dlp配置文件示例
-o ~/Downloads/%(title)s.%(ext)s
-f bestvideo+bestaudio
--write-subs
--embed-subs
--ignore-errors

🚀 基本使用教程

1. 下載單個視頻

最簡單的用法，直接下載最佳質量的視頻：

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

yt-dlp會：

  • 自動選擇最佳視頻和音頻質量
  • 分別下載視頻和音頻流
  • 使用ffmpeg自動合併
  • 保存為單個文件

2. 下載音頻

如果你只需要音頻，比如下載音樂：

# 提取音頻，不下載視頻
yt-dlp -x https://www.youtube.com/watch?v=VIDEO_ID

# 提取音頻並轉換為MP3
yt-dlp -x --audio-format mp3 --audio-quality 0 https://www.youtube.com/watch?v=VIDEO_ID

參數說明：

  • -x 或 --extract-audio：提取音頻
  • --audio-format mp3：指定輸出格式為MP3
  • --audio-quality 0：0表示最佳質量

3. 查看可用格式

在下載前，先查看有哪些可選格式：

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

輸出示例：

[info] Available formats for VIDEO_ID:
ID  EXTRESOLUTIONFPS|FILESIZE|TBRPROTO|VCODEC ACODEC
137  mp41920x108030|~200MB|https|h264 none
248  webm1920x108060|~180MB|https|vp9 none
251  webmaudioonly-|2MB|https| -           opus
140  m4aaudioonly-|3MB|https| -           aac

列說明：

  • ID：格式代碼，用於指定下載
  • EXT：文件擴展名
  • RESOLUTION：分辨率
  • FPS：幀率
  • FILESIZE：預計文件大小
  • TBR：比特率
  • VCODEC：視頻編碼器
  • ACODEC：音頻編碼器

4. 下載指定格式

根據上面的格式列表，選擇你想要的格式：

# 下載1080p視頻(mp4 137)和音頻(m4a 140)併合並
yt-dlp -f 137+140 https://www.youtube.com/watch?v=VIDEO_ID

# 使用格式選擇器
yt-dlp -f "bestvideo[height<=1080]+bestaudio" https://www.youtube.com/watch?v=VIDEO_ID

# 下載最佳質量MP4
yt-dlp -f "best[ext=mp4]" https://www.youtube.com/watch?v=VIDEO_ID

5. 自定義輸出路徑和文件名

# 使用模板
yt-dlp -o "~/Videos/%(title)s.%(ext)s" https://www.youtube.com/watch?v=VIDEO_ID

# 使用日期
yt-dlp -o "%(uploader)s_%(upload_date)s_%(title)s.%(ext)s" URL

# 分級目錄
yt-dlp -o "Downloads/%(uploader)s/%(playlist_index)s-%(title)s.%(ext)s" URL

可用的模板變量：

變量
說明
示例
%(title)s
視頻標題
"My Video"
%(uploader)s
上傳者
"John Doe"
%(upload_date)s
上傳日期
"20250207"
%(id)s
視頻ID
"abc123"
%(ext)s
擴展名
"mp4"
%(height)s
視頻高度
"1080"
%(width)s
視頻寬度
"1920"

📝 字幕下載與管理

下載字幕

# 下載視頻的同時下載字幕
yt-dlp --write-subs https://www.youtube.com/watch?v=VIDEO_ID

只下載字幕，不下載視頻

yt-dlp --write-subs --skip-download https://www.youtube.com/watch?v=VIDEO_ID

查看可用字幕

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

輸出示例：

Available subtitles for VIDEO_ID:
Language Name Formats
en       English vtt, srt
zh-Hans  Chinese vtt, srt
zh-Hant  Chinese (Traditional) vtt, srt

下載指定語言的字幕

# 下載簡體中文字幕
yt-dlp --write-subs --sub-langs "zh-Hans" https://www.youtube.com/watch?v=VIDEO_ID

# 下載多種語言
yt-dlp --write-subs --sub-langs "en,zh-Hans" https://www.youtube.com/watch?v=VIDEO_ID

# 下載自動生成字幕
yt-dlp --write-auto-subs --sub-langs "zh-Hans" URL

嵌入字幕到視頻

# 下載字幕並自動嵌入到視頻
yt-dlp --write-subs --embed-subs https://www.youtube.com/watch?v=VIDEO_ID

# 下載自動生成字幕並嵌入
yt-dlp --write-auto-subs --embed-subs URL

📊 高級格式選擇

格式選擇器

yt-dlp的格式選擇器非常強大，可以精確控制下載的格式：

# 選擇最佳質量
yt-dlp -f "bestvideo+bestaudio"

# 限制最大分辨率
yt-dlp -f "bestvideo[height<=720]+bestaudio"

# 指定編碼器
yt-dlp -f "bestvideo[vcodet=vp9]+bestaudio"

# 組合條件
yt-dlp -f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]"

# 優先選擇
yt-dlp -f "bestvideo[height<=1080][fps<=30]+bestaudio/best"

格式排序

使用-S參數可以自定義格式排序優先級：

# 按分辨率排序（默認）
yt-dlp -S "res"

# 按文件大小排序
yt-dlp -S "filesize"

# 按幀率排序
yt-dlp -S "fps"

# 組合排序
yt-dlp -S "res:1080,fps:30,codec:vp9"

# 按比特率排序（越小越好）
yt-dlp -S "+tbr"

🔄 批量下載

從文件批量下載

創建一個包含多個URL的文本文件 urls.txt：

https://www.youtube.com/watch?v=VIDEO1
https://www.bilibili.com/video/BV1...
https://vimeo.com/123456

然後批量下載：

yt-dlp -a urls.txt

下載播放列表

# 下載整個播放列表
yt-dlp --yes-playlist https://www.youtube.com/playlist?list=PLAYLIST_ID

# 只下載播放列表的前5個視頻
yt-dlp --playlist-end 5 https://www.youtube.com/playlist?list=PLAYLIST_ID

# 從第3個開始下載
yt-dlp --playlist-start 3 https://www.youtube.com/playlist?list=PLAYLIST_ID

# 下載第5到第10個
yt-dlp --playlist-start 5 --playlist-end 10 URL

錯誤處理

在批量下載時，遇到錯誤很常見：

# 忽略錯誤，繼續下載
yt-dlp --ignore-errors -a urls.txt

# 遇到錯誤停止
yt-dlp --abort-on-error -a urls.txt

# 重試指定次數
yt-dlp --retries 5 URL

# 使用緩存加速
yt-dlp --cache-dir /path/to/cache URL

🎯 SponsorBlock使用

什麼是SponsorBlock？

SponsorBlock是一個開源的數據庫，記錄YouTube視頻中廣告和贊助片段的時間戳。使用它可以自動跳過這些內容。

啓用SponsorBlock

# 跳過贊助片段
yt-dlp --sponsorblock-mark https://www.youtube.com/watch?v=VIDEO_ID

# 下載時去除贊助部分
yt-dlp --sponsorblock-remove https://www.youtube.com/watch?v=VIDEO_ID

SponsorBlock分類

SponsorBlock可以識別的片段類型：

  • sponsor：贊助商廣告
  • selfpromo：自我推廣
  • interaction：訂閲和點贊提醒
  • intro：過長的開場白
  • outro：過長的結束
  • preview：下集預告
  • music_offtopic：音樂類非主題內容

📦 可視化界面和封裝

雖然yt-dlp是命令行工具，但社區基於它開發了許多圖形化界面：

Parabolic

圖片
  • 特點：現代化界面，簡潔美觀
  • 支持：YouTube、Bilibili等1500+網站
  • 下載：視頻、音頻、縮略圖
  • 平台：Windows、macOS、Linux

MeTube

  • 特點：Web界面，適合NAS部署
  • 支持：播放列表批量下載
  • 功能：自動監控頻道更新
  • 部署：Docker一鍵部署

YT4KDownloader

  • 特點：專注於4K高質量下載
  • 支持：YouTube、Bilibili、Vimeo
  • 功能：字幕下載、元數據嵌入
  • 平台：Windows

Hitomi Downloader

  • 特點：功能強大的GUI工具
  • 支持：上千個網站
  • 功能：磁力、種子、批量下載
  • 特點：綠色免安裝

💡 最佳實踐

1. 先查看再下載

在下載前，先用-F查看可用格式，選擇最合適的：

# 查看格式
yt-dlp -F URL

# 選擇格式
yt-dlp -f 137+140 URL

2. 合理使用模板

配置文件中使用輸出模板，讓文件管理更清晰：

# ~/config/yt-dlp/config
-o ~/Downloads/%(uploader)s/%(upload_date)s/%(title)s.%(ext)s
-f bestvideo+bestaudio
--write-subs
--embed-subs

3. 批量處理優化

# 使用限制併發
yt-dlp --concurrent-fragments 4 URL

# 使用緩存
yt-dlp --cache-dir ~/.cache/yt-dlp URL

# 使用代理加速
yt-dlp --proxy socks5://127.0.0.1:1080 URL

4. 錯誤處理

# 完整的錯誤處理命令
yt-dlp \
  --ignore-errors \
  --retries 5 \
  --fragment-retries 5 \
  --continue \
  --no-overwrites \
  URL

🔍 常見問題與解決方案

問題1：某些網站無法下載

原因：網站更新了反爬蟲機制

解決：

# 使用cookies
yt-dlp --cookies-from-browser firefox URL

# 使用user-agent
yt-dlp --user-agent "Mozilla/5.0..." URL

# 使用代理
yt-dlp --proxy http://127.0.0.1:8080 URL

問題2：下載速度慢

解決：

# 使用多線程下載片段
yt-dlp --concurrent-fragments 8 URL

# 指定多個源
yt-dlp --external-downloader aria2c URL

# 使用限速避免被封
yt-dlp --limit-rate 500K URL

問題3：ffmpeg相關錯誤

錯誤：ffmpeg not found或ffmpeg version too old

解決：

# 重新安裝最新版ffmpeg
brew reinstall ffmpeg  # macOS
sudo apt install ffmpeg  # Linux

# 驗證版本
ffmpeg -version

問題4：字幕下載失敗

原因：視頻沒有字幕或字幕格式不支持

解決：

# 先檢查是否有字幕
yt-dlp --list-subs URL

# 嘗試自動生成字幕
yt-dlp --write-auto-subs URL

--list-subs

問題5：合併失敗

錯誤：WARNING: ffmpeg not found

解決：

# 安裝ffmpeg
# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg

# Windows
# 下載：https://www.gyan.dev/ffmpeg/builds/
# 添加到PATH

📊 yt-dlp vs 其他工具


📚 資源連結

  • 官方倉庫：https://github.com/yt-dlp/yt-dlp
  • 官方文檔：https://github.com/yt-dlp/yt-dlp/blob/master/README.md
  • 支持網站列表：https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md
  • 發佈版本：https://github.com/yt-dlp/yt-dlp/releases
  • Wiki文檔：https://github.com/yt-dlp/yt-dlp/wiki

總結

yt-dlp作為YouTube-dl的強力繼任者，憑藉以下特點成為視頻下載的首選工具：

  • ✅ 活躍維護：持續更新，及時修復問題
  • ✅ 功能豐富：下載、轉換、後期處理一站式解決
  • ✅ 支持廣泛：數千個網站，涵蓋主流平台
  • ✅ 靈活配置：豐富的命令行參數，滿足各種需求
  • ✅ 社區活躍：103K+ Star，強大的社區支持

無論是簡單的視頻下載，還是複雜的批量處理和格式轉換，yt-dlp都能輕鬆應對。掌握yt-dlp，讓你的視頻管理更加高效便捷！

"開源的力量，讓每個人都擁有強大的工具。"

開始使用yt-dlp，體驗開源視頻下載的強大魅力！