ytdlp.org

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

Current section

Troubleshooting guide

yt-dlp works locally but not on my server

The same command, the same yt-dlp version, the same URL: it downloads on your laptop and fails on your EC2 box, VPS, or Docker host. This is the most common yt-dlp support question right now, and the cause is almost never a bug. It's where the request comes from.

The one-line diagnosis

YouTube and most large sites score requests by IP reputation. Home and mobile IPs look like people; AWS, GCP, Azure, Hetzner, OVH, and most VPS ranges look like bots and get treated as hostile by default. Your laptop passes the same checks your server fails — not because yt-dlp behaves differently, but because the IPis different. Updating yt-dlp will not change your server's IP reputation.

This is actively confirmed by maintainers in current reports — see yt-dlp issues #17989 ("403 error even with deno (again)", opened Nov 3, 2026) and #18004 (Nov 6, 2026), where a maintainer calls the fragment 403s "classic IP blocking" unrelated to cookies or player changes.

Symptoms that point at the IP, not yt-dlp

  • • HTTP Error 403: Forbidden. Retrying fragment — downloads start, then die mid-file
  • • Sign in to confirm you're not a bot on a box that never signs in
  • • works for a few hours or days after setup, then stops — the IP got flagged
  • • heavy throttling: a download that's instant locally crawls on the server
  • • fails on a cloud host even with a current yt-dlp and a JavaScript runtime installed

If instead you see No supported JavaScript runtime could be foundor missing high-res formats, that's a different, fixable problem — see the JavaScript runtime guide.

Confirm it in 30 seconds

Run the same metadata-only probe in both places. It's cheap (no download) and isolates IP reputation from everything else:

yt-dlp --simulate -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"

If this lists formats on your laptop but 403s or returns "no formats" on the server with the same yt-dlp version (check yt-dlp --version on both), the difference is the IP. Nothing you pass to yt-dlp will fully fix a burned datacenter IP.

What actually helps (honest order)

  1. 1. Run it where the IP is clean. The simplest fix is to run the download on a residential or mobile connection (your own machine, a home server, a Raspberry Pi) and ship the file to the server afterward. Unglamorous, but it sidesteps the whole problem.
  2. 2. Route through a residential/ISP proxy. --proxy through a residential proxy makes the request look like a person again. It works, at real per-GB cost and added flakiness:
    yt-dlp --proxy "http://user:pass@residential-proxy:port" "URL"
    Datacenter proxies usually don't help — they're the same category of IP that's already blocked.
  3. 3. Pass cookies from a logged-in account. Export a cookies.txt on your local machine and use it on the server with --cookies. This raises your trust score but ties the activity to that account — never use one you care about, because automation from a datacenter IP is exactly what gets accounts flagged. Full steps in the cookies guide.
  4. 4. Try a different player client — but test it. Some reports clear 403s by switching clients, e.g. --extractor-args "youtube:player_client=web_safari". This is hit-or-miss: on a flagged IP it can return no formats at all, so verify it against your target before relying on it. It's a workaround for which client YouTube is least suspicious of, not a fix for the IP.
  5. 5. Slow down. --sleep-requests 2 and limiting concurrency extends how long an IP stays usable before it's flagged.

What doesn't help

  • • Updating again. Worth doing once to rule out a stale build, but a current yt-dlp won't change your IP's reputation. See updating yt-dlp.
  • • A datacenter VPN or datacenter proxy. Same IP category as the server — often already burned.
  • • Serverless (Lambda, Cloud Functions). The worst case: shared IP pools other people already burned, plus ffmpeg packaging and timeout pain.

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.