跳转到正文
中文
获取 API 密钥
浏览文档

指南

yt-dlp 常用命令

复制适用于视频、音频、字幕、数据集和采集恢复的命令。

本页内容

环境配置与命令约定

先安装当前的 nightly 版及全部依赖
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
deno --version
ffmpeg -version
python -m yt_dlp --list-impersonate-targets

下载命令以 Deno 和 --impersonate="" 为基础。后者需要 curl-cffi,并会选择可用的浏览器指纹。Linux/macOS 命令使用 Bash 语法。对于定时任务,确保服务环境也能使用这些依赖。

这些终端示例使用 Python 安装的 yt-dlp。使用虚拟环境中的 Python,或将 python -m yt_dlp 换成独立的 yt-dlp 命令。建议优先使用 Linux,安装指南也提供 macOS 和 Windows 步骤。安装 FFmpeg/ffprobe 用于合并流,并安装 Deno 用于执行 YouTube 挑战脚本。将示例 URL 换成源视频地址。

公约為什麼重要
引用URL和模板屏幕不同的是,它会解释像 & 、空间和偏见这样的角色。
保持 %(ext)s 在文件名中选择的媒体和后处理决定延伸。
使用 --no-playlist 为一个时钟 URL从播放列表链接的视频不应该意外地扩展你的工作。
查看您的保存配置例子可以继承全球性配置,使用 --ignore-config 为隔离测试。
Windows .bat:双模板百分比标志使用 %(id)s 在集成文件中,但 %(id)s 在互动 PowerShell 和正常配置文件中。

视频质量和 MP4

基线: 最新的夜间, Deno 和 FFmpeg,与 --impersonate="". 命令示例使用 Bash; 取代样品 URL 与您的来源。

下载一个视频与默认选择
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
使用 yt-dlp 的默认版本选择可用的流量,容器不一定是 MP4。
可用的格式列表
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"
检查代码和 audio-only/video-only 行。 数字格式 ID 不是可移动输出政策。
1080p 更喜欢
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -S "res:1080" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
偏好:如果没有在目标上或下方的格式可用,分类可以选择一个在目标上。
最大功率 1080p
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
过滤器:在没有格式相匹配时失败,保持源代码器的选择。
H.264 视频和 AAC 音频在 MP4
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
  --merge-output-format mp4 "https://www.youtube.com/watch?v=jNQXAC9IVRw"
严格的编码器选择。 需要匹配格式和 FFmpeg 单独流合。

人工智能数据集: MP4 + 容器 + 元数据

最佳视频 + 音频, MP4, 录像和 元数据
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bestvideo+bestaudio/best" --merge-output-format mp4 --remux-video mp4 \
  --write-info-json --write-subs --write-auto-subs --sub-langs "en" --sub-format "vtt/best" \
  --sleep-subtitles 5 --concurrent-fragments 1 -P dataset -o "%(id)s/%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
FFmpeg 合并源流。 MP4 保持源代码;检查解码器兼容性和标签覆盖单独。

外部下载器: aria2c

兩個連接,原住民 DASH/HLS
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --downloader aria2c \
  --downloader "dash,m3u8:native" --downloader-args "aria2c:-x 2 -s 2 -j 1" \
  --concurrent-fragments 1 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
需要安装 aria2c。先验证单个视频可以下载,再增加连接数。如果出现 403,立即减少连接。

aria2有自己的网络实施。 yt-dlp的 curl-cffi的定义不配置 aria2的指纹。如果只有外部下载器失败,请使用 --downloader native 并比较相同的源和 proxy 路线。

音频和 MP3

保存原始音频流
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
没有 MP3 转换。 有用,当您的转换或播放管道接受原始编码器。
转换为 MP3 在目标比特率
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --audio-quality 192K -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
使用 FFmpeg. 192K控制输出编码;它不恢复源质量。
M4A 无代码
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f "ba[ext=m4a]" -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
缺陷,如果没有 M4A 音频单格式可用。 添加 /ba 只有如果您的应用程序接受其他源容器。
MP3 包含集成数据和覆盖
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --embed-metadata --embed-thumbnail -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
metadata/thumbnail步骤是额外的后处理。 检查最终文件,而不仅仅是转移字符。

字幕和字幕

可用的路线列表
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
阅读此源提供的语言标签,在选择 --sub-langs 之前。
下载提供的英语字幕仅
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --sub-langs "en.*" --sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
它不会回到自动录制,也不会下载媒体。
允许自动英语捕捉
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --write-auto-subs --sub-langs "en.*" --sub-format "vtt/best" -P captions \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
可以匹配多种英语变量,这将获取可用的轨道;它不运行语音识别。
将所选的路径转换为 SRT
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-subs \
  --write-auto-subs --sub-langs "en" --convert-subs srt -P captions \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
需要 FFmpeg. 若需要,请从 --list-subs 中选择另一个语言代码。
包含在 MKV 中提供的字幕
python -m yt_dlp --js-runtimes deno --impersonate="" --write-subs --sub-langs "en" \
  --embed-subs --remux-video mkv -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
下载媒体,请求提供英语字幕,并输入可用的轨道。

查询所有字符语言可以大大增加请求和文件的数量。保持所需的语言为日常工作明确。保存源代码和语言在数据集存储库中,以免从他们描述的媒体中分离过渡。

甲状数据和输出路径

将视频的数据打印为 JSON
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --dump-json "https://www.youtube.com/watch?v=jNQXAC9IVRw" > video.json
默认模拟下载,但执行提取。 转向取代 video.json。
写完整的甲状腺数据侧面,没有媒体
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-info-json \
  -P metadata -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
创建一个 .info.json 侧面图。 这是操作提取器数据;项目领域在公开曝光之前。
下载小字只
python -m yt_dlp --js-runtimes deno --impersonate="" --skip-download --write-thumbnail \
  -P thumbnails -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
存储可用的字体在源格式。 --convert-thumbnails jpg 在需要 JPEG 时添加转换步骤。
处理后打印最终媒体路径
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --print after_move:filepath -P downloads -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
与默认阶段--print不同,一个after_move打印等待着真正的下载和其最终动作。
将完成的路径添加到一个示威
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --print-to-file after_move:filepath completed-paths.txt -P downloads \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
添加,所以退出可以产生重复输入,将其视为完成日志,而不是分复的存储。

时间范围和章节

此分類上一篇: 5 通過 10
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --download-sections "*00:00:05-00:00:10" -o "clips/%(id)s-%(section_start)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
需要 FFmpeg. 一张剪辑边界可以与可用的键盘相匹配;确认出发时准确的时间。
重新编码在所要求的切割
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --download-sections "*00:00:05-00:00:10" --force-keyframes-at-cuts \
  -o "clips/%(id)s-%(section_start)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
添加重新编码工作,以改善在所要求的边界切割。 检查结果的持续时间和 audio/video 调整。
将分类视频分成文件
python -m yt_dlp --split-chapters -o "chapter:%(id)s-%(section_number)03d.%(ext)s" \
  "https://www.youtube.com/watch?v=YOUR_VIDEO_ID"
使用视频与章节的代数据.章节的输出与原始完整下载分开;预算磁盘空间为两者。

使用不同的输出政策或档案用于剪辑和完整的视频。 源级档案输入不会编码所选择的 start/end 时间,因此一个共享的档案可以删除您打算创建的后续剪辑。

播放列表和URL列表

下载已知的URL列表
python -m yt_dlp --no-playlist --batch-file urls.txt -P collection -o "%(id)s.%(ext)s"
创建一个 UTF-8 文件,每行一个观看 URL. --no-playlist 适用于观看包含播放列表背景的 URL。
查看YouTube播放列表,无需完整的视频提取
python -m yt_dlp --flat-playlist \
  --dump-json "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > playlist.jsonl
每個入口,一個 JSON 對象。 平板入口可能忽略長度和格式細節。
下载前五个播放列表的输入
python -m yt_dlp --playlist-items 1:5 -P collection -o "%(playlist_index)03d-%(id)s.%(ext)s" \
  "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID"
播放列表指标显示命令,而不是身份。
根据日期和时间限制可用的视频
python -m yt_dlp --dateafter 20260101 --match-filters "!is_live & duration <= 1800" \
  --batch-file urls.txt
需要未活的项目,已知的持续时间高达 30 分钟,截止日期或之后的 1 月 1, 2026. 过滤可能仍然需要视频请求。
停止下载后10次下载
python -m yt_dlp --download-archive archive.txt --max-downloads 10 --batch-file urls.txt
限制控制了新下载的文件,而不是发生了多少 listing/extraction 请求。

档案与恢复

重新编写同一政策的集合
python -m yt_dlp --download-archive archive.txt --continue --no-abort-on-error -P collection \
  -o "%(id)s.%(ext)s" --batch-file urls.txt
完成的 ID 被排除。 部分下载在支持的地方重新播放。 使用相同的档案和输出路径与原始工作。
平安一个下载进程,并将退休的约束
python -m yt_dlp --sleep-requests 1 --sleep-interval 5 --max-sleep-interval 10 --retries 3 \
  --fragment-retries 3 --socket-timeout 30 --batch-file urls.txt
添加一个字符级下载进程限制,当多个过程共享路径或会议时。
转换带宽
python -m yt_dlp --js-runtimes deno --impersonate="" --limit-rate 2M \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
控制媒體轉移率。 不規則提取要求的數量。
减少原生分裂竞争
python -m yt_dlp --js-runtimes deno --impersonate="" --concurrent-fragments 1 \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
在调查时,同时开始使用一个片段403s 其他下载进程过程仍然添加自己的同步请求。

配置和文件名

只需加载您的明确收藏配置
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txt
明确命名的配置,即使是 --ignore-config 也被加载。
可读的名称与稳定身份
python -m yt_dlp --js-runtimes deno --impersonate="" -P downloads \
  -o "%(channel_id)s/%(upload_date)s-%(title).150B [%(id)s].%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
标题在此模板中被缩写为 150 字节。 ID 区分重复或更改的标题。
使用单独的临时目录
python -m yt_dlp --js-runtimes deno --impersonate="" -P "home:downloads" -P "temp:work" \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
最终步骤发生在处理后,确保两处目录有足够的空间;不同的文件系统可能需要复制。

对于长寿的收藏,决定是否应该是人可读或稳定的应用密钥。频道名称和标题可能会改变。Channel/video ID 是更好的 deduplication 关键,描述字段保留在 meta 数据中。

Cookies和运行时间路径

使用访问的浏览器配置文件
python -m yt_dlp --js-runtimes deno --impersonate="" \
  --cookies-from-browser "chrome:Profile 1" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
用您的实际浏览器配置文件取代 1 并在需要时使用会话cookies,并将其保密。
阅读现有私人Cookie文件
python -m yt_dlp --js-runtimes deno --impersonate="" --cookies private/youtube-cookies.txt \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
需要 Netscape Cookie 文件格式。 一 JSON 出口不等同。
使用下载进程PATH外的Deno执行
python -m yt_dlp --js-runtimes "deno:/opt/deno/bin/deno" --impersonate="" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
用你的下载进程安装的Deno二进制替换路径。

诊断与验证

检查清洁的抽出
python -m yt_dlp --js-runtimes deno --impersonate="" --ignore-config --verbose --simulate \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
删除默认配置并保存没有媒体,它仍然会提出提取请求,并且不会证明转移将成功。
捕捉私人诊断记录
python -m yt_dlp --js-runtimes deno --impersonate="" --ignore-config --verbose --simulate \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw" > diagnostic.log 2>&1
重新引导取代日志 编辑 cookie/header 值,代理信号和签署的 URL 之前共享。
检查保存流和持续时间
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "YOUR_OUTPUT_FILE"
使用最后的路径,处理后。 ffprobe 阅读头条;它不解码每个框架。
解密保存的文件,而不创建输出
ffmpeg -v error -i "YOUR_OUTPUT_FILE" -f null -
更深入的检查,阅读整个文件。 查看输出状态和消息。
更新 Python 包并检查其版本
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version