--- title: 'yt-dlp Proxy: How to Use --proxy with HTTP, SOCKS5 and Residential Proxies (2026)' description: 'How to use a proxy with yt-dlp: --proxy syntax for HTTP and SOCKS5, logins, config files and environment variables, which proxies YouTube blocks, rotating proxies without 403s, region-locked videos, and every proxy error with its fix.' url: https://vidkraken.com/blog/yt-dlp-proxy author: Vid Kraken published: '2026-10-28' --- # yt-dlp Proxy: How to Use --proxy with HTTP, SOCKS5 and Residential Proxies (2026) > How to use a proxy with yt-dlp: --proxy syntax for HTTP and SOCKS5, logins, config files and environment variables, which proxies YouTube blocks, rotating proxies without 403s, region-locked videos, and every proxy error with its fix. Vid Kraken · Published 2026-10-28 Source: https://vidkraken.com/blog/yt-dlp-proxy 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 **HTTP** ```bash yt-dlp --proxy "http://203.0.113.10:8080" "https://www.youtube.com/watch?v=VIDEO_ID" ``` **With a login** ```bash yt-dlp --proxy "http://user:password@203.0.113.10:8080" "https://www.youtube.com/watch?v=VIDEO_ID" ``` **SOCKS5** ```bash yt-dlp --proxy "socks5h://user:password@203.0.113.10:1080" "https://www.youtube.com/watch?v=VIDEO_ID" ``` **No proxy** ```bash 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: **Linux / macOS** ```bash mkdir -p ~/.config/yt-dlp echo '--proxy http://user:password@203.0.113.10:8080' >> ~/.config/yt-dlp/config ``` **Windows** ```bash # %APPDATA%\yt-dlp\config.txt --proxy http://user:password@203.0.113.10: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](https://vidkraken.com/blog/yt-dlp-api), pass `"proxy": "http://user:password@203.0.113.10:8080"` in the options dictionary. ## Which proxies work with YouTube The proxy only helps if YouTube trusts its IP more than yours. | Proxy type | On YouTube | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Datacenter proxies and most VPNs | Often blocked, the same way your cloud server is: "[Sign in to confirm you're not a bot](https://vidkraken.com/blog/yt-dlp-sign-in-to-confirm-not-a-bot)" or [403 errors](https://vidkraken.com/blog/yt-dlp-403-forbidden) | | Residential proxies | Work most often. Usually billed per GB of traffic | | Mobile proxies | Also work well, at a higher price | | Tor | Most exit nodes are flagged, so expect bot checks and slow downloads | | Free proxy lists | Avoid. Slow, often already flagged, and the operator can see and change your traffic | ### 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. ```bash 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](https://vidkraken.com/blog/youtube-metadata-api) returns a video's `regionRestriction`: the countries it's allowed or blocked in. ## Proxy errors and how to fix them | Error contains | Cause | Fix | | ---------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | | `Unable to connect to proxy` … `Connection refused` | Wrong host or port, or the proxy is down | Check the address. Try it with `curl -x` | | `Tunnel connection failed: 407 Proxy Authentication Required` | Wrong username or password, or your IP isn't on the provider's allowlist | Check the login, URL-encode special characters, or allowlist your server's IP | | `SocksHTTPSConnection` … `Failed to establish a new connection` | The SOCKS proxy is unreachable | Check the address and port, and that the scheme is `socks5`/`socks5h`, not `http` | | `Read timed out` | A slow or overloaded proxy | Raise `--socket-timeout` (for example `30`), or use another proxy | | A bot check, but only through the proxy | The proxy's IP is flagged | Use a residential proxy or another exit IP | | 403 partway through a download | The IP changed mid-video | Use a sticky session | | `The uploader has not made this video available in your country` | The proxy is in a blocked country | Use a proxy in an allowed country | For anything else, run the command with `-v` and see [yt-dlp not working](https://vidkraken.com/blog/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](https://vidkraken.com/blog/youtube-download-api-error-codes) such as `GEO_RESTRICTED`, and failed downloads aren't charged. See the [YouTube downloader API guide](https://vidkraken.com/blog/youtube-downloader-api). > **No proxies to buy, rotate or debug.** > > Send a YouTube URL, get a direct MP4 or MP3 link. You pay for bandwidth only, > and failed downloads are free. > > [Start free](https://vidkraken.com/login) ## Frequently asked questions **How do I use a proxy with yt-dlp?** Add --proxy with the proxy's URL: yt-dlp --proxy "http\://user:password\@host:port" "VIDEO\_URL". For SOCKS5, use socks5:// or socks5h://. To use it every time, put the --proxy line in \~/.config/yt-dlp/config (Linux and macOS) or %APPDATA%\yt-dlp\config.txt (Windows). **Does yt-dlp support SOCKS5 proxies?** Yes. Use socks5://host:port, or socks5h://host:port to resolve domain names through the proxy too. socks4 and socks4a work as well. Add user:password@ before the host if the proxy needs a login. **What kind of proxy works best for YouTube with yt-dlp?** Residential or mobile proxies. YouTube often blocks datacenter proxies and VPNs the same way it blocks cloud servers, and most Tor exit nodes are flagged. **Can I use a VPN with yt-dlp?** Yes. A VPN routes all traffic on your machine, so yt-dlp uses it without any extra flag. VPN IPs are shared datacenter IPs, though, and YouTube often treats them like cloud servers, with bot checks or 403s. To send only yt-dlp through the VPN, use your provider's SOCKS5 or HTTP proxy address with --proxy, if it has one. **Why do I get 403 errors with a rotating proxy?** YouTube's stream URLs are tied to the IP that requested them. If the proxy switches IP between loading the video page and downloading the file, the download gets 403. Use a sticky session so one video keeps one IP, and rotate between videos. **Can yt-dlp bypass YouTube region restrictions?** Only with a proxy in a country where the video is allowed. --xff and --geo-bypass don't work on YouTube, and --geo-verification-proxy isn't used for YouTube. **Does yt-dlp use the HTTP\_PROXY environment variable?** Yes. Without --proxy, yt-dlp uses HTTPS\_PROXY and HTTP\_PROXY. If only HTTP\_PROXY is set, it's used for HTTPS too. Pass --proxy "" to connect directly and ignore them.