# yt-dlp 常用命令

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

规范链接： https://flashdata.dev/zh/docs/guides/yt-dlp-commands
FlashData 核查于 2026-11-13

- [视频与音频](https://flashdata.dev/zh/docs/guides/yt-dlp-commands/reference.md#video) — 质量、代码和 MP3
- [收藏和甲状数据](https://flashdata.dev/zh/docs/guides/yt-dlp-commands/reference.md#subtitles) — ⁇ 和结构化产量
- [收藏和恢复](https://flashdata.dev/zh/docs/guides/yt-dlp-commands/reference.md#archives) — 列表、档案和配置
- [诊断失败](https://flashdata.dev/zh/docs/guides/yt-dlp-commands/reference.md#diagnostics) — 记录和输出验证

<a id="conventions"></a>

## 环境配置与命令约定


**先安装当前的 nightly 版及全部依赖**

```bash
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 和正常配置文件中。 |

- [安装工具](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [建立可重复使用的集合配置](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#repeatable)

<a id="video"></a>

## 视频质量和 MP4


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

**下载一个视频与默认选择**

```bash
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。

**可用的格式列表**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

检查代码和 audio-only/video-only 行。 数字格式 ID 不是可移动输出政策。

**1080p 更喜欢**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -S "res:1080" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

偏好：如果没有在目标上或下方的格式可用，分类可以选择一个在目标上。

**最大功率 1080p**

```bash
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**

```bash
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 单独流合。

> **容器不是代码**
> --merge-output-format选择合并容器。 --remux-video重新包装兼容的流。也不能把 AV1 转换为 H.264。当一个解码器需要一个特定的编码器时，选择该编码器或计划一个单独的转码。

- [了解选项和落后](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#formats)

<a id="dataset"></a>

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


**最佳视频 + 音频, MP4, 录像和 元数据**

```bash
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 保持源代码；检查解码器兼容性和标签覆盖单独。

- [数据集输出政策和缺席的封面](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [相同的 Python 数据集选项](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#dataset)

<a id="aria2"></a>

## 外部下载器: aria2c


**兩個連接，原住民 DASH/HLS**

```bash
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 路线。

- [连接控制和通道诊断](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#aria2)

<a id="audio"></a>

## 音频和 MP3


**保存原始音频流**

```bash
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 在目标比特率**

```bash
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 无代码**

```bash
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 包含集成数据和覆盖**

```bash
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步骤是额外的后处理。 检查最终文件，而不仅仅是转移字符。

<a id="subtitles"></a>

## 字幕和字幕


**可用的路线列表**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

阅读此源提供的语言标签，在选择 --sub-langs 之前。

**下载提供的英语字幕仅**

```bash
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"
```

它不会回到自动录制，也不会下载媒体。

**允许自动英语捕捉**

```bash
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**

```bash
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 中提供的字幕**

```bash
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"
```

下载媒体，请求提供英语字幕，并输入可用的轨道。

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

<a id="metadata"></a>

## 甲状数据和输出路径


**将视频的数据打印为 JSON**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --dump-json "https://www.youtube.com/watch?v=jNQXAC9IVRw" > video.json
```

默认模拟下载，但执行提取。 转向取代 video.json。

**写完整的甲状腺数据侧面，没有媒体**

```bash
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 侧面图。 这是操作提取器数据；项目领域在公开曝光之前。

**下载小字只**

```bash
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 时添加转换步骤。

**处理后打印最终媒体路径**

```bash
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打印等待着真正的下载和其最终动作。

**将完成的路径添加到一个示威**

```bash
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"
```

添加，所以退出可以产生重复输入，将其视为完成日志，而不是分复的存储。

- [Python 数据预测](https://flashdata.dev/zh/docs/guides/yt-dlp-python-api/reference.md#metadata)

<a id="clips"></a>

## 时间范围和章节


**此分類上一篇: 5 通過 10**

```bash
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. 一张剪辑边界可以与可用的键盘相匹配；确认出发时准确的时间。

**重新编码在所要求的切割**

```bash
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 调整。

**将分类视频分成文件**

```bash
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 时间，因此一个共享的档案可以删除您打算创建的后续剪辑。

<a id="playlists"></a>

## 播放列表和URL列表


**下载已知的URL列表**

```bash
python -m yt_dlp --no-playlist --batch-file urls.txt -P collection -o "%(id)s.%(ext)s"
```

创建一个 UTF-8 文件，每行一个观看 URL. --no-playlist 适用于观看包含播放列表背景的 URL。

**查看YouTube播放列表，无需完整的视频提取**

```bash
python -m yt_dlp --flat-playlist \
  --dump-json "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > playlist.jsonl
```

每個入口，一個 JSON 對象。 平板入口可能忽略長度和格式細節。

**下载前五个播放列表的输入**

```bash
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"
```

播放列表指标显示命令，而不是身份。

**根据日期和时间限制可用的视频**

```bash
python -m yt_dlp --dateafter 20260101 --match-filters "!is_live & duration <= 1800" \
  --batch-file urls.txt
```

需要未活的项目，已知的持续时间高达 30 分钟，截止日期或之后的 1 月 1, 2026. 过滤可能仍然需要视频请求。

**停止下载后10次下载**

```bash
python -m yt_dlp --download-archive archive.txt --max-downloads 10 --batch-file urls.txt
```

限制控制了新下载的文件，而不是发生了多少 listing/extraction 请求。

<a id="archives"></a>

## 档案与恢复


**重新编写同一政策的集合**

```bash
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 被排除。 部分下载在支持的地方重新播放。 使用相同的档案和输出路径与原始工作。

**平安一个下载进程，并将退休的约束**

```bash
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
```

添加一个字符级下载进程限制，当多个过程共享路径或会议时。

**转换带宽**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --limit-rate 2M \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

控制媒體轉移率。 不規則提取要求的數量。

**减少原生分裂竞争**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --concurrent-fragments 1 \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

在调查时，同时开始使用一个片段403s 其他下载进程过程仍然添加自己的同步请求。

> **档案有特定的工作**
> 它在成功下载后记录了 extractor/video ID。它不是输出设置的目录或检查文件仍然存在。保持单独的音频、视频和剪辑政策档案，并不要用 --force-write-archive 标记失败的工作完成。

- [可重复使用的配置和恢复程序](https://flashdata.dev/zh/docs/guides/how-to-use-yt-dlp/reference.md#repeatable)

<a id="configuration"></a>

## 配置和文件名


**只需加载您的明确收藏配置**

```bash
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txt
```

明确命名的配置，即使是 --ignore-config 也被加载。

**可读的名称与稳定身份**

```bash
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 区分重复或更改的标题。

**使用单独的临时目录**

```bash
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 数据中。

<a id="session"></a>

## Cookies和运行时间路径


**使用访问的浏览器配置文件**

```bash
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文件**

```bash
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执行**

```bash
python -m yt_dlp --js-runtimes "deno:/opt/deno/bin/deno" --impersonate="" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

用你的下载进程安装的Deno二进制替换路径。

- [Cookie 加载、终止和机器人检查](https://flashdata.dev/zh/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)

<a id="diagnostics"></a>

## 诊断与验证


**检查清洁的抽出**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --ignore-config --verbose --simulate \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

删除默认配置并保存没有媒体，它仍然会提出提取请求，并且不会证明转移将成功。

**捕捉私人诊断记录**

```bash
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 之前共享。

**检查保存流和持续时间**

```bash
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "YOUR_OUTPUT_FILE"
```

使用最后的路径，处理后。 ffprobe 阅读头条；它不解码每个框架。

**解密保存的文件，而不创建输出**

```bash
ffmpeg -v error -i "YOUR_OUTPUT_FILE" -f null -
```

更深入的检查，阅读整个文件。 查看输出状态和消息。

**更新 Python 包并检查其版本**

```bash
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version
```

- [第403章 按阶段](https://flashdata.dev/zh/docs/guides/yt-dlp-403-forbidden/reference.md)
- [429: 数据和标签请求限制](https://flashdata.dev/zh/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [诊断一个Bot-Check答案](https://flashdata.dev/zh/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [完整的Upstream选项参考](https://github.com/yt-dlp/yt-dlp#usage-and-options)
