yt-dlp

yt-dlp开源项目 是 youtube-dl 的fork项目，提供了新功能和patch(合并了很多修复)，可以解决一些下载问题。

安装

  • pip 安装:

    python3 -m pip install -U yt-dlp

  • Homebrew 安装:

    # 安装
brew install yt-dlp
# 更新
brew upgrade yt-dlp

备注

配置方法和 youtube-dl 基本相同，例如配置文件是 ~/.config/yt-dlp/config

提取cookies

警告

2025年时是用 yt-dlp 可以通过cookies来访问和下载YouTube视频，但是由于YouTube收紧了安全限制，当前(2026年)已经无法简单通过cookies来访问YouTube。

备注

由于YouTube处于安全会经常轮转cookies，所以需要导出一个不会变化的cookies，也就是 robots 使用的cookies

要下载油管文件，需要为 yt-dlp 提供cookies。有以下一些方法

使用 yt-dlp 提取chrome的cookies

yt-dlp 无需使用第三方就可以提取chrome浏览器的cookie:

提取chrome的cookies
yt-dlp --cookies-from-browser chrome --cookies cookies.txt

上述命令将浏览器的cookies保存为cookies.txt文件。这个cookies.txt文件后续就可以 --cookies 参数用于下载油管文件。不过，需要注意这个cookies.txt包含了所有网站的cookies，所以一定要保障安全。

使用 chrome 保存cookies

chrome 的私有浏览窗口可以导出cookies:

  • 在浏览器中使用一个新的 private browsing/incognito 窗口，并登陆到YouTube

  • 在同一个窗口和相同的tab中，访问 https://www.youtube.com/robots.txt

  • 使用第三方export cookies来输出当前incognito窗口的cookies:

../../_images/get_cookies.txt_locally.png

在chrome中激活 "Allow in Incognito" 选项以后可以使用 Get cookies.txt LOCALLY chrome插件 保存当前页面的cookies

备注

chrome处于incongnito状态时，代理配置使用的是系统设置proxy(默认情况下常规的proxy插件不生效，除非配置 "Allow in Incognito")。我是通过设置系统代理方式来实现incognito 窗口访问YouTube

JavaScript支持

在2025年使用 yt-dlp 的时候，例如，下文的使用其扫描 《杀死那个石家庄人》--万能青年旅店 影视混剪MV

获取指定YouTube的URL中文件列表
yt-dlp -F "https://www.youtube.com/watch?v=npHbCnf-Lpk" --cookies www.youtube.com_cookies.txt

可能会出现无法找到JavaScript运行时的报错(如果系统没有安装 Node.js 的话):

获取指定YouTube的URL中文件列表报错: 没有找到JS运行时
[youtube] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk
[youtube] npHbCnf-Lpk: Downloading webpage
[youtube] npHbCnf-Lpk: Downloading tv downgraded player API JSON
WARNING: [youtube] npHbCnf-Lpk: Signature solving failed: Some formats may be missing. Ensure you have a supported JavaScript runtime and challenge solver script distribution installed. Review any warnings presented before this message. For more details, refer to  https://github.com/yt-dlp/yt-dlp/wiki/EJS
WARNING: [youtube] npHbCnf-Lpk: n challenge solving failed: Some formats may be missing. Ensure you have a supported JavaScript runtime and challenge solver script distribution installed. Review any warnings presented before this message. For more details, refer to  https://github.com/yt-dlp/yt-dlp/wiki/EJS
WARNING: Only images are available for download. use --list-formats to see them
[info] Available formats for npHbCnf-Lpk:
ID  EXT   RESOLUTION FPS │ PROTO │ VCODEC MORE INFO
────────────────────────────────────────────────────
sb3 mhtml 48x27        0 │ mhtml │ images storyboard
sb2 mhtml 80x45        0 │ mhtml │ images storyboard
sb1 mhtml 160x90       0 │ mhtml │ images storyboard
sb0 mhtml 320x180      0 │ mhtml │ images storyboard

按照提示参考 yt-dlp: External JS Scripts Setup Guide 安装一个支持的JavaScript Runtime。其中推荐 Deno

不过，我实际上在 macOS工作室 中使用了 mise 安装了 Node.js ，所以这里可以通过传递参数 --js-runtimes node 或 --js-runtimes node:~/.local/share/mise/installs/node/24/bin/node 来解决:

通过指定nodejs作为JavaSrcipt runtime获取指定YouTube的URL中文件列表
yt-dlp -F "https://www.youtube.com/watch?v=npHbCnf-Lpk" --cookies www.youtube.com_cookies.txt --js-runtimes node

不过，我有遇到新的报错:

提示需要 solver script 来解决remote component challenge
[youtube] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk
[youtube] npHbCnf-Lpk: Downloading webpage
[youtube] npHbCnf-Lpk: Downloading tv downgraded player API JSON
[youtube] npHbCnf-Lpk: Downloading player 445213fb-main
[youtube] [jsc:node] Solving JS challenges using node
WARNING: [youtube] [jsc] Remote component challenge solver script (node) was skipped. It may be required to solve JS challenges. You can enable the download with  --remote-components ejs:github  (recommended). For more information and alternatives, refer to  https://github.com/yt-dlp/yt-dlp/wiki/EJS
WARNING: [youtube] npHbCnf-Lpk: Signature solving failed: Some formats may be missing. Ensure you have a supported JavaScript runtime and challenge solver script distribution installed. Review any warnings presented before this message. For more details, refer to  https://github.com/yt-dlp/yt-dlp/wiki/EJS
WARNING: [youtube] npHbCnf-Lpk: n challenge solving failed: Some formats may be missing. Ensure you have a supported JavaScript runtime and challenge solver script distribution installed. Review any warnings presented before this message. For more details, refer to  https://github.com/yt-dlp/yt-dlp/wiki/EJS
WARNING: Only images are available for download. use --list-formats to see them
[info] Available formats for npHbCnf-Lpk:
ID  EXT   RESOLUTION FPS │ PROTO │ VCODEC MORE INFO
────────────────────────────────────────────────────
sb3 mhtml 48x27        0 │ mhtml │ images storyboard
sb2 mhtml 80x45        0 │ mhtml │ images storyboard
sb1 mhtml 160x90       0 │ mhtml │ images storyboard
sb0 mhtml 320x180      0 │ mhtml │ images storyboard

这是因为 yt-dlp 需要EJS challenge solver脚本才能通过YouTube的challenge，如果没有执行安装 pip install -U "yt-dlp[default]" 就没有包含这个 yt-dlp-ejs 包，所以这里需要下载和激活ejs脚本:

增加 --remote-components ejs:github 参数可以自动下载和更新ejs
yt-dlp -F "https://www.youtube.com/watch?v=npHbCnf-Lpk" --cookies www.youtube.com_cookies.txt --js-runtimes node --remote-components ejs:github

使用

我非常喜欢的 《杀死那个石家庄人》--万能青年旅店 影视混剪MV

  • 首先获取视频列表:

获取指定YouTube的URL中文件列表(2026年方法)
yt-dlp -F "https://www.youtube.com/watch?v=npHbCnf-Lpk" --cookies www.youtube.com_cookies.txt --js-runtimes node --remote-components ejs:github

这里参数 --cookies www.youtube.com_cookies.txt 是指定刚才从chrome的Incognito页面export出来的cookie文件

显示输出:

yt-dlp -F 列出下载视频的输出案例 《杀死那个石家庄人》--万能青年旅店 影视混剪MV
[youtube:tab] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk&list=PLnqzKl0S_xnl8xgGJxWKDPuFrgafqSEfo&index=3
[youtube:tab] Downloading playlist PLnqzKl0S_xnl8xgGJxWKDPuFrgafqSEfo - add --no-playlist to download just the video npHbCnf-Lpk
[youtube:tab] PLnqzKl0S_xnl8xgGJxWKDPuFrgafqSEfo: Downloading webpage
WARNING: [youtube:tab] Unable to recognize playlist. Downloading just video npHbCnf-Lpk
[youtube] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk
[youtube] npHbCnf-Lpk: Downloading webpage
[youtube] npHbCnf-Lpk: Downloading android player API JSON
[info] Available formats for npHbCnf-Lpk:
ID  EXT   RESOLUTION FPS CH │   FILESIZE   TBR PROTO │ VCODEC        VBR ACODEC      ABR ASR MORE INFO
────────────────────────────────────────────────────────────────────────────────────────────────────────────────
sb2 mhtml 48x27        0    │                  mhtml │ images                                storyboard
sb1 mhtml 80x45        0    │                  mhtml │ images                                storyboard
sb0 mhtml 160x90       0    │                  mhtml │ images                                storyboard
599 m4a   audio only      2 │    1.50MiB   31k dash  │ audio only        mp4a.40.5   31k 22k ultralow, m4a_dash
600 webm  audio only      2 │    1.74MiB   36k dash  │ audio only        opus        36k 48k ultralow, webm_dash
139 m4a   audio only      2 │    2.37MiB   49k dash  │ audio only        mp4a.40.5   49k 22k low, m4a_dash
249 webm  audio only      2 │    2.57MiB   53k dash  │ audio only        opus        53k 48k low, webm_dash
250 webm  audio only      2 │    3.37MiB   69k dash  │ audio only        opus        69k 48k low, webm_dash
140 m4a   audio only      2 │    6.29MiB  129k dash  │ audio only        mp4a.40.2  129k 44k medium, m4a_dash
251 webm  audio only      2 │    6.56MiB  135k dash  │ audio only        opus       135k 48k medium, webm_dash
17  3gp   176x144      7  1 │    3.77MiB   78k https │ mp4v.20.3     78k mp4a.40.2    0k 22k 144p
597 mp4   256x144     15    │    1.63MiB   34k dash  │ avc1.4d400b   34k video only          144p, mp4_dash
598 webm  256x144     15    │    1.38MiB   28k dash  │ vp9           28k video only          144p, webm_dash
160 mp4   256x144     30    │    3.60MiB   74k dash  │ avc1.4d400c   74k video only          144p, mp4_dash
278 webm  256x144     30    │    3.63MiB   75k dash  │ vp9           75k video only          144p, webm_dash
133 mp4   426x240     30    │    8.22MiB  169k dash  │ avc1.4d4015  169k video only          240p, mp4_dash
242 webm  426x240     30    │    5.89MiB  121k dash  │ vp9          121k video only          240p, webm_dash
134 mp4   640x360     30    │   15.75MiB  324k dash  │ avc1.4d401e  324k video only          360p, mp4_dash
18  mp4   640x360     30  2 │ ~ 22.52MiB  452k https │ avc1.42001E  452k mp4a.40.2    0k 44k 360p
243 webm  640x360     30    │    9.95MiB  205k dash  │ vp9          205k video only          360p, webm_dash
135 mp4   854x480     30    │   29.06MiB  598k dash  │ avc1.4d401f  598k video only          480p, mp4_dash
244 webm  854x480     30    │   16.39MiB  337k dash  │ vp9          337k video only          480p, webm_dash
22  mp4   1280x720    30  2 │ ~ 63.28MiB 1270k https │ avc1.64001F 1270k mp4a.40.2    0k 44k 720p
136 mp4   1280x720    30    │   55.51MiB 1142k dash  │ avc1.64001f 1142k video only          720p, mp4_dash
247 webm  1280x720    30    │   29.94MiB  616k dash  │ vp9          616k video only          720p, webm_dash
137 mp4   1920x1080   30    │  102.77MiB 2115k dash  │ avc1.640028 2115k video only          1080p, mp4_dash
248 webm  1920x1080   30    │   48.61MiB 1000k dash  │ vp9         1000k video only          1080p, webm_dash

我来下载最小的一个视频mp4，编号 18 :

下载指定YouTube URL中文件(2026年方法)
yt-dlp -f 18 "https://www.youtube.com/watch?v=npHbCnf-Lpk" --cookies www.youtube.com_cookies.txt --js-runtimes node --remote-components ejs:github

备注

请注意，上述列表中，很多视频文件是没有声音的( video only )，有些则只有声音( audio only )。如果你需要一个完整的有声音的视频，务必 不要 选择 video only 。

显示输出:

[youtube:tab] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk
[youtube:tab] Downloading playlist PLnqzKl0S_xnl8xgGJxWKDPuFrgafqSEfo - add --no-playlist to download just the video npHbCnf-Lpk
[youtube:tab] PLnqzKl0S_xnl8xgGJxWKDPuFrgafqSEfo: Downloading webpage
WARNING: [youtube:tab] Unable to recognize playlist. Downloading just video npHbCnf-Lpk
[youtube] Extracting URL: https://www.youtube.com/watch?v=npHbCnf-Lpk
[youtube] npHbCnf-Lpk: Downloading webpage
[youtube] npHbCnf-Lpk: Downloading android player API JSON
[info] npHbCnf-Lpk: Downloading 1 format(s): 18
[dashsegments] Total fragments: 1
[download] Destination: /Users/huataihuang/Movies/《杀死那个石家庄人》--万能青年旅店   影视混剪MV.mp4
[download] 100% of    22MiB in 00:00:04 at 399.36KiB/s

非常赞!!!

结合 Sphinx文档嵌入视频 就可以在我的个人网站上嵌入一段演示视频: 墙裂推荐观看YouTube原高清视频 => 《杀死那个石家庄人》--万能青年旅店 影视混剪MV

快速下载喜爱的音频文件

经常听的的歌曲，建一个 playlist 列表，可以使用 yt-dlp 获取这个列表中的所有视频的IDs:

获取 playlist 列表所有视频的IDs
yt-dlp --get-id --flat-playlist "<playlist_URL>" --cookies www.youtube.com_cookies.txt

然后一次性从Youtube下载音频:

下载自己喜欢的歌曲
#!/usr/bin/env bash
#
:<<'EOF'
获得音质最好的音频
yt-dlp -F 过滤列表案例
599 m4a   audio only      2 |   1.45MiB   31k dash  | audio only        mp4a.40.5   31k 22k ultralow, m4a_dash
139 m4a   audio only      2 |   2.30MiB   49k dash  | audio only        mp4a.40.5   49k 22k low, m4a_dash
140 m4a   audio only      2 |   6.11MiB  129k dash  | audio only        mp4a.40.2  129k 44k medium, m4a_dash
EOF

# 将要下载的id都保存到playlist文件中，然后就可以自动把这些视频一一过滤出合适的id(需要的音频格式)
#
# yt-dlp --download-archive archive.txt "<playlist_URL>"
# 不过，上述命令会同时下载一次最近原始视频文件，然后存放一个列表到 archive.txt ，不过这个方法不太好
#
# 更好的获取playlist中所有视频IDs的方法是:
# yt-dlp --get-id --flat-playlist "<playlist_URL>"

# 这里的URL请修订成自己需要的真实playlist
playlist_URL="https://www.youtube.com/playlist?list=XXXXXXXXXXXX"

yt-dlp --get-id --flat-playlist $playlist_URL --cookies www.youtube.com_cookies.txt > video_ids.txt

for i in `cat video_ids.txt`;do
    id=`yt-dlp -F "https://www.youtube.com/watch?v=$i" | grep "m4a   audio only" | awk '{print $1" "$8}' | awk -Fk '{print $1}' | sort -r -n -k2 | head -1 | awk '{print $1}'`
    echo $id
    yt-dlp -f $id "https://www.youtube.com/watch?v=$i"
done

配置

上述我在命令行使用了多个参数，如果每次都这么输入其实非常麻烦， yt-dlp 提供了一种配置方法，简单来说就是共用的参数存储在 yt-dlp.conf 中，每个参数一行:

yt-dlp.conf 配置文件距离
--cookies www.youtube.com_cookies.txt
--js-runtimes node
--remote-components ejs:github

然后执行命令就非常简单，只需要目标URL了，例如:

简化的yt-dlp命令
yt-dlp -F "https://www.youtube.com/watch?v=npHbCnf-Lpk"

备注

yt-dlp.conf 配置文件可以存放在 当前目录 或者:

yt-dlp.conf 路径
# Home Configuration:
# 当使用-P参数yt-dlp.conf位于home目录
# 如果没有使用-P参数，则搜索当前目录

# User Configuration:
${XDG_CONFIG_HOME}/yt-dlp.conf
${XDG_CONFIG_HOME}/yt-dlp/config (recommended on Linux/macOS)
${XDG_CONFIG_HOME}/yt-dlp/config.txt
${APPDATA}/yt-dlp.conf
${APPDATA}/yt-dlp/config (recommended on Windows)
${APPDATA}/yt-dlp/config.txt
~/yt-dlp.conf
~/yt-dlp.conf.txt
~/.yt-dlp/config
~/.yt-dlp/config.txt

# System Configuration:
/etc/yt-dlp.conf
/etc/yt-dlp/config
/etc/yt-dlp/config.txt

参考