Skip to content
EN
Get API key
Browse documentation

Guides

How to use yt-dlp

A Linux-first workflow for daily downloads: nightly setup, formats, captions, datasets and resumable collections.

On this page

Install the daily-use baseline

Start with nightly + Deno + FFmpeg. Use a project virtual environment and enable browser impersonation with --impersonate="". The Linux setup below installs the tools; macOS and Windows alternatives are in the tabs.

Ubuntu / Debian example with Python 3.11+. Install the system tools, create a project virtual environment, then install the current nightly and its extras. Run Deno's installer as the same user who owns the worker.

Linux worker setup
sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg aria2 curl unzip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
curl -fsSL https://deno.land/install.sh -o /tmp/install-deno.sh
sh /tmp/install-deno.sh
export PATH="$HOME/.deno/bin:$PATH"
deno --version
python -m yt_dlp --version
ToolWhat it doesCheck
Python 3.11+Runs the Python package and examples in this series.python --version
Latest yt-dlp nightly + default,curl-cffi extrasCurrent YouTube extractor, matching EJS solver and browser impersonation support.python -m yt_dlp --version
FFmpeg and ffprobeMerge streams, convert audio, cut clips and inspect saved media.ffmpeg -version / ffprobe -version
Deno 2.3+ (required in this workflow)Runs YouTube challenges. Install it on every worker, not only your development machine.deno --version

Install the executables too. [default] supplies the EJS scripts; Deno is separate. FFmpeg and ffprobe must also be on the worker’s PATH.

Check the complete baseline
deno --version
ffmpeg -version
ffprobe -version
python -m pip show yt-dlp yt-dlp-ejs curl-cffi
python -m yt_dlp --list-impersonate-targets
The final command should list available browser targets. If targets are unavailable, check that curl-cffi is installed in this exact virtual environment.
Test extraction with Deno and browser impersonation
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose \
  --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Inspect the JS runtimes and request-handler lines. A simulation tests extraction; follow it with a real transfer.

FlashData’s operating baseline includes --impersonate="": it lets curl-cffi choose an available browser fingerprint. This changes the request fingerprint; it does not provide login cookies, solve JavaScript challenges or change the exit IP. If this option slows a working route or introduces errors, repeat the same one-video test without it and keep the working configuration.

Check the release before putting it on a worker

Get executables from the official project's release page, or install the Python package from its published package source. If downloading a standalone binary, compare its SHA-256 with the matching filename in that release's SHA2-256SUMS. Record the release and checksum with your worker image so you can identify exactly what ran.

Hash the downloaded file
sha256sum yt-dlp

A checksum comparison is useful only when the expected value comes from the trusted release, not the same unknown mirror as the executable. If security software flags a file, investigate its source and report before making an exception. Open-source availability alone is not evidence that every downloaded binary or third-party plugin is safe.

Treat shared configuration files as code to review: options such as --exec can launch commands, and plugins add code to the downloader process. Keep browser cookies, proxy credentials and signed URLs out of configuration examples and diagnostic reports.

Download one video

Use one short video first. Quote the URL, add --no-playlist, and name the file by video ID. The command prints the final path after merging and post-processing.

One video, one output folder
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
  -o "%(id)s.%(ext)s" --print after_move:filepath \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
The printed path is the file after merging and post-processing. Open that path; do not assume the file will end in .mp4.

Without a format override, yt-dlp chooses its preferred available streams. High-quality sources often have separate video and audio streams, so two transfers followed by an FFmpeg merge are normal. Intermediate files and a .part file may appear while the job is running.

Choose quality and codecs

Inspect this video's formats
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"

Choose a policy, not a copied format ID. Check resolution, codecs and separate audio/video tracks. Format IDs can differ between sources.

Selector or optionMeaningWhen to use it
bv + baChoose a video-only stream and an audio-only stream; FFmpeg combines them.You need both tracks and can merge locally.
A/BTry selector A, then B if A is unavailable.Define an explicit fallback instead of assuming every source has the same formats.
[height<=1080]Exclude streams above 1080 pixels high.A hard upper bound is a requirement.
-S res:1080Prefer resolution up to 1080; can select a larger one when none below is available.1080p is a preference rather than a hard ceiling.
--merge-output-format mp4Choose the container when merging separate streams.You already selected compatible streams. It does not transcode codecs.
Keep the source codecs, with a hard 1080p ceiling
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" -P downloads \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
This can produce WebM, MP4 or another supported container. It fails if no format meets the ceiling; it does not silently download 4K.

For an editor or playback stack that specifically requires H.264 video and AAC audio, filter those codecs and merge to MP4. MP4 is a container: a stream in an MP4 container can still contain a codec your application cannot decode.

Request H.264 + AAC, up to 1080p
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 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
If the required codecs are unavailable, this strict selector fails. Decide whether to accept different source codecs or transcode; do not remove the requirement by accident.

Remuxing repackages streams without re-encoding them. Transcoding changes codecs and consumes CPU while potentially changing quality. Use --remux-video when the streams already fit the target container; use a deliberate FFmpeg conversion when a downstream decoder requires different codecs.

Save audio or MP3

If your transcription pipeline accepts the source audio codec, download that stream directly. This avoids an unnecessary lossy conversion. MP3 is useful when a consumer specifically requires it; a high MP3 bitrate cannot restore detail already lost in the source.

Keep the best available 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"
Expect the source container and codec, commonly M4A/AAC or WebM/Opus.
Convert audio to MP3
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --audio-quality 0 -P audio -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Requires FFmpeg. --audio-quality 0 selects its best variable-quality setting; use a bitrate such as 192K when your downstream specification requires one.

Save captions and metadata

A useful collection needs more than filenames. Keep video IDs, source URLs, titles, durations and available captions so you can search the collection and trace an asset back to its source. Start by listing the caption tracks; requesting en does not mean every video has an English track.

Inspect captions, then save English tracks without media
python -m yt_dlp --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
python -m yt_dlp --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"
--write-subs selects supplied subtitles; --write-auto-subs also permits automatic captions. This retrieves existing tracks and does not transcribe a video that has none.
Media with metadata and a thumbnail
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --write-info-json \
  --write-thumbnail -P downloads -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"

The .info.json file is detailed operational metadata, not a clean public API response. It can include expiring media URLs and request-related fields. Keep the full sidecar with the collection, and export only the fields your downstream system needs. If you need SRT instead of VTT, add --convert-subs srt and ensure FFmpeg is available.

Build an AI dataset item

For a training collection, decide the media and text outputs together. A common requirement is the best available video and audio, merged into MP4, with timestamped captions and extraction metadata kept under the same video ID. A resolution ceiling useful for previews is usually the wrong default for a source-quality dataset.

Download one complete dataset item
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" \
  --print after_move:filepath "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Bash example. FFmpeg merges separate streams; --remux-video also covers a combined-stream fallback. Use an exact language tag from --list-subs; replace en with the language your dataset needs.

Start with one exact caption language. In our live check, en.* selected en, en-en and en-de; the third track returned 429 before media downloading began. A caption error can stop the item at that stage. After a cooldown, retry only the required track, or split media and caption jobs if your collection must keep media ingestion moving.

The /best fallback permits a combined video/audio stream when separate tracks are unavailable. Remove that fallback if your collection contract requires separate bestvideo and bestaudio sources. MP4 does not mean H.264: this recipe keeps the selected source codecs. Use the strict H.264/AAC selector above if your training decoder requires those codecs, or transcode as a separate, recorded step.

Expected files when an English caption track exists
dataset/VIDEO_ID/
  VIDEO_ID.mp4
  VIDEO_ID.info.json
  VIDEO_ID.en.vtt
The caption suffix uses the actual language tag. No caption file is created when the requested track is unavailable; do not mark text coverage complete just because the MP4 finished.
RequirementCollection decision
Highest available source qualityUse bestvideo+bestaudio, keep source codecs and verify the merged streams with ffprobe.
Timestamped textKeep VTT/SRT segments and language alongside the video ID. Flattening text discards timing needed for clip alignment.
Missing captionsRecord missing text explicitly. Route the saved audio to your transcription stage if text is mandatory.
Captions for many languagesRequest only the required languages. Every additional track adds requests and can encounter 429 independently of media.
Resumable media + text deliveryUse a separate dataset archive and an inventory with media, metadata and caption states. An archive entry does not prove all required sidecars exist.

Do not reuse an archive created by an earlier media-only run for this new policy: archived videos may be skipped before their missing captions are collected. Either run the dataset policy with its own archive or schedule a separate caption-repair pass for IDs missing text. Store original captions; if your model needs clean transcript text, derive it in a versioned processing step.

Improve transfer throughput without overwhelming an IP

aria2c can help when a single connection underuses an unreliable or high-latency link. It cannot repair a refused player request or a flagged exit IP. First make the native downloader work on one source; then compare transfer time and errors with a small number of aria2 connections.

Start with two connections per HTTP transfer
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 -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
Install aria2 first. Keep DASH/HLS with the native downloader here so segment concurrency stays explicit.
ControlWhat it limits
aria2c -x 2Connections to one server for a download.
aria2c -s 2Requested splits for one file; splitting also depends on file size and server support.
aria2c -j 1Concurrent items inside that aria2 invocation, not other yt-dlp workers.
--concurrent-fragments 1Fragment downloads inside the native DASH/HLS downloader.
Your job queueThe total active videos sharing the same host or proxy exit IP.

curl-cffi impersonation belongs to yt-dlp’s own requests; it does not configure aria2’s TLS fingerprint. If native downloads work but aria2 gets 403, return to native before changing unrelated extractor settings. Keep extraction and the external transfer on the same proxy session.

In FlashData’s operation, raising concurrency too aggressively can make a working route start returning 403 immediately. If this happens, stop the other jobs, go back to one worker and one connection, then retest. Do not compensate by adding more aria2 splits or retrying the same denied stream in parallel. If that IP remains rejected at low load, use the 403 IP-replacement workflow.

Conservative native transfer for comparison
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --downloader native --concurrent-fragments 1 --limit-rate 2M \
  --sleep-requests 2 --sleep-interval 5 --max-sleep-interval 10 \
  -P diagnostics "https://www.youtube.com/watch?v=jNQXAC9IVRw"
2M is a diagnostic bandwidth cap, not a universal YouTube threshold. Raise throughput gradually only after the route is working.

Prepare a collection

For a small known set, create a UTF-8 urls.txt with one watch URL per line. For a YouTube playlist, first enumerate its IDs into a manifest. Flat extraction inspects the playlist listing without doing a full extraction for every video; it is useful for scope review, but its entries can lack duration, formats and availability details.

Create a YouTube playlist manifest
python -m yt_dlp --flat-playlist --print "https://www.youtube.com/watch?v=%(id)s" \
  "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > urls.txt
Replace YOUR_PLAYLIST_ID. Inspect urls.txt before starting the media transfer. The redirect replaces this manifest if you run it again.

To trial a collection, select a few playlist entries with --playlist-items 1:5. A channel's /videos tab is a clearer starting point for uploaded videos than an ambiguous channel homepage. Do not treat playlist order as identity: items can be inserted, reordered or removed.

FilterUseConsequence
--playlist-items 1:5First five entries in the current listing.Useful for a small trial, not a durable checkpoint.
--dateafter 20260101Keep entries dated on or after January 1, 2026.Date filtering may still require per-video extraction.
--match-filters "!is_live & duration <= 1800"Require a non-live item with a known duration at most 30 minutes.Entries with unknown duration do not match this strict filter.
--download-archive archive.txtSkip source IDs already recorded by earlier downloads.Works across changed titles and playlist positions.

Resume a collection safely

Save the following as yt-dlp-work.conf in your collection folder, beside urls.txt. It defines the output policy once, gives the collection its own archive, and limits retries. Keep output files and this archive together: an archive records success by extractor and ID, not by the current file's checksum or location.

yt-dlp-work.conf
# YouTube worker baseline
--js-runtimes deno
--impersonate=""
--concurrent-fragments 1

# Output policy
--no-playlist
-f "bv*[height<=1080]+ba/b[height<=1080]"
-P downloads
-o "%(channel_id)s/%(id)s.%(ext)s"
--write-info-json

# Resume and remember completed media
--continue
--download-archive archive.txt
--no-abort-on-error

# Bound each attempt and spread out work
--retries 5
--fragment-retries 5
--socket-timeout 30
--sleep-requests 1
--sleep-interval 5
--max-sleep-interval 10

# Append paths only after the final move
--print-to-file after_move:filepath completed-paths.txt
Plain text configuration, one option per line. Paths in this example are relative to the working directory. Use absolute paths when a scheduler may start elsewhere.
Run the collection
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txt
--ignore-config removes implicit user/system configuration; an explicitly supplied --config-locations file is still loaded.

Rerun the same command after an interruption. Completed IDs are skipped, and resumable partial transfers continue where supported. Extraction failures can be revisited on the next run. The default .part files are useful state; do not delete them as a routine retry step.

--no-abort-on-error continues past unavailable inputs, but a run can still exit nonzero and post-processing errors need attention. Avoid adding --ignore-errors merely to get a green job: it can treat post-processing failures as successful downloads. Review the log and completed outputs before declaring the collection complete.

Check the finished files

The completed-paths.txt file is a useful starting inventory. Test the actual final output rather than a temporary video-only stream. ffprobe reads container and stream metadata; a separate decoding pass catches problems that a readable header alone will miss.

Inspect one finished file
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "downloads/CHANNEL_ID/VIDEO_ID.mp4"
Replace the path with one from completed-paths.txt. Check expected duration, required audio/video streams and decoder-compatible codecs.
Optional full decode check
ffmpeg -v error -i "downloads/CHANNEL_ID/VIDEO_ID.mp4" -f null -
Reads and decodes the whole file without creating a new media output. Check the exit status as well as messages; this takes longer than ffprobe.
FindingWhat to do
Only a .part or separate stream file remainsInspect the transfer/merge error and resume the original job; do not label the intermediate file complete.
Video plays without soundInspect the selected format and ffprobe streams. A video-only format needs an audio selection and merge.
MP4 will not open in your editorInspect the codecs, not just the extension; select compatible streams or transcode explicitly.
Archived ID but no local fileCheck whether the file was moved/deleted. Reconcile the inventory before changing archive entries.

9. Move a proven command into a scheduled job

Run the complete command successfully by hand before scheduling it. A scheduler usually starts with a different PATH and working directory. Give it the virtual environment's full Python path, the full config path and an explicit working directory; also make FFmpeg and the JavaScript runtime available to that process.

  • Use a single worker for a collection/archive. Do not let yesterday's run overlap today's run against the same outputs.
  • On Linux, use a timer/service or cron entry with a working directory and a lock such as flock. Keep logs outside the media folder and rotate them.
  • On macOS, use launchd with absolute executable and working-directory paths.
  • On Windows Task Scheduler, set Program to the environment's python.exe, Arguments to -m yt_dlp plus the config and batch options, and Start in to the collection folder.
  • Record start/end time, executable version, source manifest, exit status and completed/failed counts. A nonzero batch exit does not imply every item failed.
  • Keep cookie files and destination credentials out of the shared configuration repository. Give a job only the credentials it needs.

The sleep options in the config act within one process. Ten workers using the same settings still produce ten overlapping streams of requests. Increasing --concurrent-fragments changes fragment concurrency inside a download, not the number of videos in your job queue.

Choose the right error guide

Update this Python environment
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version

When a previously working source breaks, update to the latest nightly first, including the matching extras. For the standalone binary use yt-dlp --update-to nightly; -U alone stays on the current channel. Run a small canary after each update, then rebuild the workers and record the revision so the fleet does not silently mix releases.

SymptomStart here
Requested format is not availableList formats and inspect your strict filters before changing retries.
ffmpeg not found / ffprobe and ffmpeg not foundCheck PATH from the actual worker or scheduler account.
JavaScript challenge / missing runtime warningVerify runtime detection and the matching EJS package.
HTTP 403 during transferIdentify the refused host and stage; separate extraction from media transfer.
HTTP 429Pause the affected IP, allow a cooldown and lower extraction/caption request frequency.
Sign in to confirm you’re not a botPause the batch and diagnose one source, session and network.

When the output belongs in a cloud pipeline

If you want to own the downloader, the workflows above give you control over files, formats and processing. If your application needs completed media delivered to storage, FlashData provides tracked YouTube download jobs, bot handling, proxy routing and retries. Your application submits the source and output settings, then keeps the job ID and delivery record.

Reference material

The upstream option reference is the source of truth for your installed version. Use these sections when changing a collection policy or updating a worker image.