ytdlp.org

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

Current section

Server guide

Using a proxy with yt-dlp

When yt-dlp 403s or hits a bot check on a server, a proxy is the usual next idea. It can work — but only the right kind, and not for every failure. Here is how the --proxy flag works, the one distinction that decides whether it helps at all, and where a proxy stops being worth the trouble.

The flag

One option routes all of yt-dlp's traffic through a proxy. It takes an HTTP, HTTPS, or SOCKS URL, with optional credentials:

# HTTP / HTTPS proxy
yt-dlp --proxy "http://user:pass@proxy.example:8080" "URL"

# SOCKS5 (resolve DNS through the proxy with socks5h)
yt-dlp --proxy "socks5h://user:pass@127.0.0.1:1080" "URL"

# force a direct connection for one run, ignoring any env proxy
yt-dlp --proxy "" "URL"

If you have several IPs on the box and just want to pick which one goes out, you don't need a proxy at all — bind the source address:

yt-dlp --source-address 203.0.113.10 "URL"

The part that actually decides it: datacenter vs residential

This is where most people waste money. YouTube's block is about IP reputation, not the proxy mechanism. A cheap "datacenter" proxy is still a datacenter IP — the same category as your server — so routing through it changes nothing. You swap one flagged IP for another and still get Sign in to confirm you're not a bot.

What clears the wall is a residentialor mobile proxy, where the exit IP belongs to a real ISP connection. Those are the ones YouTube doesn't treat as automatically suspicious. They're also the expensive ones — usually billed per gigabyte, with rotating pools you point yt-dlp at:

yt-dlp --proxy "http://user:pass@residential.example:port" "URL"

This is the same wall covered in yt-dlp works locally but not on my server and for transcript libraries in YouTube transcripts that fail on a server.

Geo-restriction is a different problem

Don't confuse a bot block with a region block. If a video is simply unavailable in your server's country, you want a proxy in the right country, and yt-dlp can use a separate proxy just to pass the geo check while downloading over your main connection:

yt-dlp --geo-verification-proxy "http://proxy-in-target-country:8080" "URL"

A residential proxy fixes reputation; a correctly-located proxy fixes geo-blocking. They are not the same lever.

What a proxy still won't fix

A proxy only changes where your request comes from. It doesn't give yt-dlp a JavaScript runtime for player challenges (see the Docker JS runtime guide) and it doesn't mint the GVS PO token YouTube now wants (see the PO token provider guide). If formats keep getting skipped after you add a good proxy, those are the next things to check.

Where a proxy stops being worth it

For a laptop or a one-off, skip the proxy entirely — run yt-dlp locally where your own IP is fine. A residential proxy earns its cost only when you must run on a server at some volume, and even then it's real ongoing work: a paid, per-gigabyte line item, pools that themselves get flagged over time, and rotation logic to maintain. If you're getting into that, and the job only needs the file, metadata, or transcript rather than yt-dlp itself, a hosted API that already runs on rotating residential IPs removes the proxy problem from your side of the line. That's the honest case for Importly for server and agent workloads.

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.