ytdlp.org

Practical yt-dlp docs: install, commands, fixes, cookies, and workflows.

Current section

Troubleshooting guide

YouTube downloads that stall and time out

The download starts, pulls a chunk, then freezes for several seconds, pulls the next chunk, freezes again — and eventually dies with Read timed out or X bytes read, Y more expected (where X + Y adds up to the chunk size). The request isn't being blocked — the bytes are being handed to you slowly. This is YouTube throttling the media stream, and it has its own set of fixes, separate from a 403 or a bot wall.

What you're actually seeing

[download]  31.2% of ~380.00MiB at  650.00KiB/s ETA 08:11
WARNING: Read timed out. Retrying (1/10)...
WARNING: [download] Got error: 9437184 bytes read, 1048576 more expected

YouTube serves the stream in chunks (often ~10MB) and paces how fast it releases each one. When a chunk comes too slowly, yt-dlp's socket read hits its timeout before the chunk finishes — that's Read timed out. When the connection drops mid-chunk, you get N bytes read, M more expected. It is not the same as a 429 / bot check (your request is allowed) or a missing-format error (you have the URL). The fix is to make the download survive the slow patches — and, where you can, shake off the throttle.

Fix 1: update first

How yt-dlp requests the stream, and which client it uses, changes constantly — and throttling is partly per-client. A current build is the cheapest fix:

yt-dlp -U
yt-dlp --update-to nightly   # throttling workarounds often land here first

Fix 2: let the download ride out the stalls

If a stall aborts the whole job, the real loss is that you gave up. Raise the socket timeout, retry forever, and resume instead of restarting:

yt-dlp \
  --socket-timeout 30 \
  --retries infinite \
  --fragment-retries infinite \
  --retry-sleep fragment:exp=1:20 \
  --continue \
  "https://www.youtube.com/watch?v=VIDEO_ID"
  • --socket-timeout 30 — wait longer before calling a slow read dead (default is shorter, so slow chunks trip it).
  • --retries infinite / --fragment-retries infinite — keep retrying the HTTP request and each fragment instead of the default 10.
  • --retry-sleep fragment:exp=1:20 — exponential backoff between fragment retries (1s, 2s, 4s… capped at 20s), so you back off when YouTube is squeezing.
  • --continue — resume the partial file; a fresh retry picks up where it stalled rather than re-downloading.

Fix 3: --throttled-rate to re-trigger extraction

This is the flag built for exactly this. --throttled-rate sets a minimumacceptable download rate. If the rate drops below it, yt-dlp assumes it's being throttled, re-extracts fresh stream URLs, and restarts the download — which often lands you on an un-throttled path:

yt-dlp --throttled-rate 100K \
  --retries infinite --fragment-retries infinite --continue \
  "https://www.youtube.com/watch?v=VIDEO_ID"

Pick a floor well under your normal speed (e.g. 100K) so it only triggers on a genuine stall, not ordinary variance.

Fix 4: smaller chunks, and a different client

A smaller HTTP chunk size means each request is smaller, so a stall costs you less and sometimes sidesteps the per-chunk pacing:

yt-dlp --http-chunk-size 1M --continue "https://www.youtube.com/watch?v=VIDEO_ID"

For DASH/HLS formats you can also pull fragments in parallel with -N 4 (--concurrent-fragments) — keep it modest, because hammering with many parallel requests is exactly what gets an IP flagged. And because throttling is partly per-client, switching the player client sometimes lands on a less throttled path — see choosing a YouTube player_client.

If it only crawls on a server

Here's the tell: the same command runs at full speed on your home connection but crawls or times out on an AWS/GCP/Hetzner box. None of the flags above change that, because YouTube throttles flagged datacenter IP ranges far harder than residential ones — it's the IP, not your config. See yt-dlp works locally but not on my server for what actually helps there.

Servers & agents

Works on your laptop but not on the server?

Paste a link to see what a hosted API returns from a clean residential IP — no cookies, proxies, or runtime to maintain on the box.

Straightforward yt-dlp help for installs, commands, fixes, cookies, and repeatable workflows.

ytdlp.org is an independent, community-maintained documentation site. It is not affiliated with the yt-dlp project — the official source code lives at github.com/yt-dlp/yt-dlp.