yt-dlp Proxy: How to Use --proxy with HTTP, SOCKS5 and Residential Proxies (2026)

You usually need a proxy with yt-dlp for one of three reasons: YouTube blocks your server's IP, you're downloading in bulk and getting rate-limited, or a video is blocked in your country.

Short version: add --proxy "http://user:pass@host:port" (or socks5://...) to your command. On YouTube, datacenter proxies are usually blocked just like your server is, so use residential proxies. If you rotate them, keep one IP per video. A proxy in an allowed country is also the only way yt-dlp can get a region-locked YouTube video; --xff doesn't work for YouTube.

The --proxy syntax

yt-dlp --proxy "http://203.0.113.10:8080" "https://www.youtube.com/watch?v=VIDEO_ID"

yt-dlp --proxy "http://user:[email protected]:8080" "https://www.youtube.com/watch?v=VIDEO_ID"

yt-dlp --proxy "socks5h://user:[email protected]:1080" "https://www.youtube.com/watch?v=VIDEO_ID"

yt-dlp --proxy "" "https://www.youtube.com/watch?v=VIDEO_ID"

• Schemes: http, https, socks4, socks4a, socks5 and socks5h. An https:// proxy needs the requests package, which pip install "yt-dlp[default]" and the official executables include.
• socks5 or socks5h: with socks5h, the proxy also looks up domain names. Use it when DNS from your machine is blocked, or when you don't want your own DNS server to see what you download.
• Special characters in the password: if it contains #, /, ? or %, URL-encode them (# becomes %23), or yt-dlp will read the URL wrongly.
• Everything goes through it: the YouTube page, the API calls and the video file itself. If your proxy bills per GB, every download counts against it.

Set it once

Rather than adding --proxy to every command, put it in yt-dlp's config file:

mkdir -p ~/.config/yt-dlp
echo '--proxy http://user:[email protected]:8080' >> ~/.config/yt-dlp/config

# %APPDATA%\yt-dlp\config.txt
--proxy http://user:[email protected]:8080

Two other ways:

• Environment variables. If you don't pass --proxy, yt-dlp uses HTTPS_PROXY and HTTP_PROXY, like most command-line tools. If only HTTP_PROXY is set, it's used for HTTPS as well. --proxy "" ignores them.
• Python. In the yt-dlp Python API, pass "proxy": "http://user:[email protected]:8080" in the options dictionary.

Which proxies work with YouTube

The proxy only helps if YouTube trusts its IP more than yours.

What about a VPN?

yt-dlp needs no flag to use a VPN. A VPN routes all of the machine's traffic, so yt-dlp goes through it automatically. The catch is the IP: VPN servers sit in datacenters and are shared by many users, so YouTube often gives them the same bot checks as a cloud server. If you want only yt-dlp's traffic to go through the VPN, check whether your provider offers a SOCKS5 or HTTP proxy address, and pass that to --proxy.

Test a proxy before you rely on it. If yt-dlp --proxy "..." --simulate "URL" gets a bot check on a public video that works from home, the proxy's IP is flagged.

Rotating proxies without 403s

yt-dlp uses one proxy for the whole command. It doesn't rotate by itself. There are two common setups:

• A list of proxies: pick a different one for each video.
• A rotating gateway: one address, and the provider changes the IP behind it.

With either, keep the same IP for the whole video. YouTube's stream URLs are tied to the IP that requested them. If a rotating gateway switches IP between the page request and the download, or during the download, you get a 403 partway through. Most providers offer "sticky" sessions that hold one IP for a few minutes; use those, and rotate between videos rather than within one.

while read -r url; do
  proxy=$(shuf -n 1 proxies.txt)
  yt-dlp --proxy "$proxy" --sleep-requests 1 "$url"
done < urls.txt

Rotation spreads your requests across IPs, but it doesn't make bulk downloading invisible. Keep pauses between requests (--sleep-requests, --sleep-interval), especially if you see HTTP Error 429.

Region-locked videos

YouTube decides what's blocked from the IP it sees, so you need a proxy in a country where the video is allowed. Two options look like they'd help but don't do anything on YouTube:

• --xff and --geo-bypass fake an X-Forwarded-For header. They help on some sites, but yt-dlp turns them off for YouTube, where a faked header doesn't help.
• --geo-verification-proxy is used by some other sites to check your location. yt-dlp's YouTube extractor never uses it; YouTube downloads go through --proxy.

To find a country to use, Vid Kraken's metadata endpoint returns a video's regionRestriction: the countries it's allowed or blocked in.

Proxy errors and how to fix them

For anything else, run the command with -v and see yt-dlp not working.

When proxies stop being worth it

For a handful of downloads, one decent residential proxy is enough. At scale, the proxies become the work: paying per GB for every download (including the failed ones), finding IPs YouTube hasn't flagged yet, sticky sessions, retries, and countries for region-locked videos. All of it changes whenever YouTube does.

If downloads are a feature of your product, a managed API takes that off your hands. With Vid Kraken, you send a YouTube URL and get a direct link to the file on our CDN. Bot detection, proxies and YouTube's changes are handled on our side. When a video can't be downloaded, you get a typed error code such as GEO_RESTRICTED, and failed downloads aren't charged. See the YouTube downloader API guide.

Frequently asked questions