Skip to content
EN
Get API key
Browse documentation

Guides

yt-dlp commands for everyday work

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

On this page

Setup and command conventions

Start from the current nightly and complete dependencies
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.

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

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

AI dataset: MP4 + captions + metadata

Best video + audio, MP4, captions and metadata
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.

External downloader: aria2c

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

Audio and MP3

Save the original audio stream
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
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
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
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.

Captions and subtitles

List available tracks
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
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
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
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
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.

Metadata and output paths

Print one video's metadata as JSON
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
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
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
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
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.

Time ranges and chapters

Download seconds 5 through 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"
Requires FFmpeg. A clip boundary can align with available keyframes; verify the output when exact timing matters.
Re-encode around requested cuts
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
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.

Playlists and URL lists

Download a known URL list
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
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
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
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
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.

Archives and recovery

Resume a collection with the same policy
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
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
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
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.

Configuration and filenames

Load only your explicit collection config
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
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
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.

Cookies and runtime paths

Use the browser profile that has access
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
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
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.

Diagnostics and verification

Inspect a clean extraction
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
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
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
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
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version