# yt-dlp commands for everyday work

Copy a recipe for video, audio, captions, datasets or collection recovery.

Canonical reference: https://flashdata.dev/docs/guides/yt-dlp-commands
Reviewed: 2026-11-13 by FlashData

- [Video and audio](https://flashdata.dev/docs/guides/yt-dlp-commands/reference.md#video) — Quality, codecs and MP3
- [Captions and metadata](https://flashdata.dev/docs/guides/yt-dlp-commands/reference.md#subtitles) — Sidecars and structured output
- [Collections and recovery](https://flashdata.dev/docs/guides/yt-dlp-commands/reference.md#archives) — Lists, archives and config
- [Diagnose a failure](https://flashdata.dev/docs/guides/yt-dlp-commands/reference.md#diagnostics) — Logs and output verification

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

## Setup and command conventions


**Start from the current nightly and complete dependencies**

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

The download recipes use Deno and --impersonate="" as the baseline. The latter requires curl-cffi and lets it choose an available browser fingerprint. Linux/macOS commands use Bash syntax; for a scheduled worker, also make these dependencies available in that service environment.

These terminal examples use the Python installation of yt-dlp. Use your virtual-environment Python, or replace python -m yt_dlp with the standalone yt-dlp command. Use Linux first, with macOS and Windows alternatives in the setup guide. Install FFmpeg/ffprobe for merging and Deno for YouTube challenge solving. Replace the example URL with your source.

| Convention | Why it matters |
| --- | --- |
| Quote URLs and templates | The shell otherwise interprets characters such as &, spaces and parentheses. |
| Keep %(ext)s in filenames | The selected media and post-processing determine the extension. |
| Use --no-playlist for a watch URL | A video linked from a playlist should not unexpectedly expand your job. |
| Check your saved configuration | Examples may inherit a global config. Use --ignore-config for an isolated test. |
| Windows .bat: double template percent signs | Use %%(id)s in a batch file, but %(id)s in interactive PowerShell and normal config files. |

- [Install the tools](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#install)
- [Build a reusable collection configuration](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#repeatable)

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

## Video quality and MP4


**Baseline:** latest nightly, Deno and FFmpeg, with `--impersonate=""`. The recipes use Bash; replace the sample URL with your source.

**Download one video with default selection**

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

Selects available streams using yt-dlp's defaults. The container is not necessarily MP4.

**List available formats**

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

Inspect codecs and audio-only/video-only rows. Numeric format IDs are not portable output policies.

**Prefer 1080p**

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

A preference: if no format at or below the target is available, sorting can pick one above it.

**Enforce a maximum of 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"
```

A filter: fails when no format matches. Retains the source codec choice.

**H.264 video and AAC audio in 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"
```

Strict codec selection. Requires matching formats and FFmpeg for separate-stream merging.

> **Container is not codec**
> --merge-output-format chooses the merged container. --remux-video repackages compatible streams. Neither turns AV1 into H.264. When a decoder requires a specific codec, select that codec or plan a separate transcode.

- [Understand selectors and fallbacks](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#formats)

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

## AI dataset: MP4 + captions + metadata


**Best video + audio, MP4, captions and metadata**

```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 merges source streams. The MP4 keeps source codecs; check decoder compatibility and caption coverage separately.

- [Dataset output policy and missing captions](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#dataset)
- [Equivalent Python dataset options](https://flashdata.dev/docs/guides/yt-dlp-python-api/reference.md#dataset)

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

## External downloader: aria2c


**Two connections, native 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"
```

Requires the aria2c executable. Increase connections only after a working single-video baseline; reduce them immediately if 403s appear.

aria2 has its own network implementation. yt-dlp's curl-cffi impersonation does not configure aria2's fingerprint. If only the external downloader fails, use --downloader native and compare the same source and proxy route.

- [Connection controls and throughput diagnosis](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#aria2)

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

## Audio and MP3


**Save the original audio stream**

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

No MP3 conversion. Useful when your transcription or playback pipeline accepts the original codec.

**Convert to MP3 at a target bitrate**

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

Uses FFmpeg. 192K controls the output encoding; it does not restore source quality.

**Prefer M4A without transcoding**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f "ba[ext=m4a]" -P audio \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

Fails if no M4A audio-only format is available. Add /ba only if your application accepts other source containers.

**MP3 with embedded metadata and cover**

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

The metadata/thumbnail steps are additional post-processing. Check the final file, not just the transfer hook.

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

## Captions and subtitles


**List available tracks**

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

Read the language tags offered by this source before choosing --sub-langs.

**Download supplied English subtitles only**

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

Does not fall back to automatic captions and does not download the media.

**Also permit automatic English captions**

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

en.* can match multiple English variants. This retrieves available tracks; it does not run speech recognition.

**Convert selected tracks to 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"
```

Requires FFmpeg. Select another language code from --list-subs if needed.

**Embed supplied subtitles in 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"
```

Downloads media, requests supplied English subtitles and embeds the available track. Check whether that track exists first.

Requesting all caption languages can greatly increase the number of requests and files. Keep the requested languages explicit for routine work. Preserve the source ID and language in your dataset inventory so transcripts do not get detached from the media they describe.

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

## Metadata and output paths


**Print one video's metadata as JSON**

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

Simulates the download by default, but performs extraction. The redirect replaces video.json.

**Write a full metadata sidecar without media**

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

Creates an .info.json sidecar. This is operational extractor data; project fields before exposing it publicly.

**Download the thumbnail only**

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

Saves the available thumbnail in its source format. --convert-thumbnails jpg adds a conversion step when JPEG is required.

**Print the final media path after processing**

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

Unlike a default-stage --print, an after_move print waits for a real download and its final move.

**Append completed paths to a manifest**

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

Appends, so retries may produce repeated entries. Treat it as a completion log, not a deduplicated inventory.

- [Python metadata projection](https://flashdata.dev/docs/guides/yt-dlp-python-api/reference.md#metadata)

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

## Time ranges and chapters


**Download seconds 5 through 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"
```

Requires FFmpeg. A clip boundary can align with available keyframes; verify the output when exact timing matters.

**Re-encode around requested cuts**

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

Adds re-encoding work to improve cutting at the requested boundaries. Inspect the resulting duration and audio/video alignment.

**Split a chaptered video into files**

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

Use a video with chapter metadata. Chapter outputs are separate from the original full download; budget disk space for both.

Use a different output policy or archive for clips and full videos. A source-level archive entry does not encode the selected start/end times, so one shared archive can suppress a later clip you intended to create.

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

## Playlists and URL lists


**Download a known URL list**

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

Create a UTF-8 file with one watch URL per line. --no-playlist applies to watch URLs that include playlist context.

**Inspect a YouTube playlist without full video extraction**

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

One JSON object per entry. Flat entries may omit duration and format details.

**Download the first five playlist entries**

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

Playlist indices are display order, not identity. Keep the video ID in the filename.

**Limit eligible videos by date and duration**

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

Requires non-live items with known duration up to 30 minutes, dated on or after January 1, 2026. Filtering can still require per-video requests.

**Stop after ten new downloads**

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

The limit controls newly downloaded files, not how many listing/extraction requests occur. Keep the archive for the next run.

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

## Archives and recovery


**Resume a collection with the same policy**

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

Completed IDs are skipped. Partial downloads resume where supported. Use the same archive and output paths as the original job.

**Pace one worker and bound its retries**

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

These are per-process settings. Add a queue-level worker limit when several processes share a route or session.

**Cap transfer bandwidth**

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

Controls media transfer rate. It does not regulate the number of extraction requests.

**Reduce native fragment concurrency**

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

Start with one fragment at a time when investigating 403s. Other worker processes still add their own concurrent requests.

> **The archive has a specific job**
> It records extractor/video IDs after successful downloads. It is not a catalog of output settings or a check that a file still exists. Keep separate archives for audio, video and clip policies, and do not mark failed work complete with --force-write-archive.

- [A reusable config and recovery procedure](https://flashdata.dev/docs/guides/how-to-use-yt-dlp/reference.md#repeatable)

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

## Configuration and filenames


**Load only your explicit collection config**

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

The explicitly named config is loaded even with --ignore-config. Use full paths for scheduled jobs.

**Readable names with stable identity**

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

The title is truncated to 150 bytes in this template. IDs distinguish duplicate or changing titles.

**Use a separate temporary directory**

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

The final move happens after processing. Ensure both directories have enough space; different filesystems can require a copy.

For long-lived collections, decide whether filenames should be human-readable or stable application keys. Channel names and titles can change. Channel/video IDs are better keys for deduplication, with descriptive fields kept in metadata.

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

## Cookies and runtime paths


**Use the browser profile that has access**

```bash
python -m yt_dlp --js-runtimes deno --impersonate="" \
  --cookies-from-browser "chrome:Profile 1" \
  --no-playlist "https://www.youtube.com/watch?v=jNQXAC9IVRw"
```

Replace Profile 1 with your actual browser profile. Use session cookies only when needed, and keep them private.

**Read an existing private cookie file**

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

Requires Netscape cookie-file format. A JSON export is not equivalent.

**Use a Deno executable outside the worker PATH**

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

Replace the path with the Deno binary installed for your worker.

- [Cookie loading, expiry and bot checks](https://flashdata.dev/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)

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

## Diagnostics and verification


**Inspect a clean extraction**

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

Removes implicit config and saves no media. It still makes extraction requests and does not prove a transfer will succeed.

**Capture a private diagnostic log**

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

The redirect replaces the log. Redact cookie/header values, proxy credentials and signed URLs before sharing.

**Inspect saved streams and duration**

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

Use the final path, after processing. ffprobe reads the headers; it does not decode every frame.

**Decode the saved file without creating output**

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

A deeper check that reads the whole file. Check the exit status and messages.

**Update the Python package and check its version**

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

- [Diagnose 403 by stage](https://flashdata.dev/docs/guides/yt-dlp-403-forbidden/reference.md)
- [429: metadata and caption request limits](https://flashdata.dev/docs/guides/yt-dlp-429-too-many-requests/reference.md)
- [Diagnose a bot-check response](https://flashdata.dev/docs/guides/yt-dlp-sign-in-not-a-bot/reference.md)
- [Complete upstream option reference](https://github.com/yt-dlp/yt-dlp#usage-and-options)
