yt-dlp has one proxy option, --proxy, and it carries every request yt-dlp makes itself. It does not always reach the programs that yt-dlp hands a download to. ffmpeg gets the proxy as a variable and cannot use SOCKS. Websocket downloads take only SOCKS, and two helper programs get no proxy at all. The one other proxy option, --geo-verification-proxy, covers a few dozen sites and never YouTube. We read every setting on this page in yt-dlp's docs and code at release 2026.08.19, the newest on 19 September 2026.
Why does yt-dlp get refused on a server?
Many video sites judge the address before anything else. We tested this from our server on 19 September 2026. It sits in a hosting network. Each site got the same plain request twice, with a Chrome browser name and no cookies. The video links are test cases from yt-dlp's own code.
| Site | What our server IP got |
|---|---|
| YouTube, two test videos | the page, with the player's verdict "Sign in to confirm you’re not a bot" |
| Vimeo | Cloudflare's page "Verify to continue" instead of the video |
| Bilibili | HTTP 412, an error page |
| SoundCloud | the track page |
YouTube refused both videos on the first request, in both runs. So the block did not wait for a few hundred requests, as some guides claim. It came with the first request. Dailymotion served a page, but we did not test whether its video data followed. TikTok's test video has gone private, so it told us nothing about the IP.
YouTube's message is the one yt-dlp prints as an error. Cookies and PO tokens are part of that fix, and our guide to the bot message covers them. This page covers the proxy side.
How do I set a proxy in yt-dlp?
Pass it on the command line:
yt-dlp --proxy "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT" "https://www.youtube.com/watch?v=VIDEO_ID"
To use it on every run, put the same option in yt-dlp's config file. On Linux and macOS the file is ~/.config/yt-dlp/config, and on Windows it is %APPDATA%\yt-dlp\config. The file holds command options, one per line:
--proxy http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT
Without --proxy, yt-dlp looks in the environment. It reads HTTP_PROXY, HTTPS_PROXY and ALL_PROXY, and the lowercase name wins when both exist. An HTTP_PROXY alone covers HTTPS sites too. With no variable set, it falls back to the system proxy of Windows or macOS. That explains a common surprise: yt-dlp can use a proxy that nobody gave it. --proxy "" turns all of this off for one run, and hosts in NO_PROXY skip the proxy.
A proxy written as host:port, with no scheme, counts as http://host:port.
Which proxy URL should I write?
Write http:// for almost every proxy, HTTPS sites included. The scheme names the link to the proxy, not the site. An https:// proxy URL means that link is encrypted, and few proxies offer that. yt-dlp's built-in HTTP client cannot open one. It needs the requests library, version 2.31 or newer, or curl_cffi. Without them it stops with "To use an HTTPS proxy for this request, one of the following dependencies needs to be installed: requests, curl_cffi". The standalone release binaries include requests. A maintainer answered one user who hit this: "Are you sure your proxy is HTTPS? It doesn't appear to be".
socks5:// works too, with a username and password. yt-dlp lets the proxy resolve host names, as if you wrote socks5h://, so no name lookup leaves your machine. socks:// counts as SOCKS4.
Each part of yt-dlp takes a different set of proxy URLs. The chart shows which.
What does the proxy not reach?
yt-dlp can hand a download to another program. It passes the proxy to each one in a different way:
| Program | What yt-dlp passes |
|---|---|
| yt-dlp itself, the default | the proxy you set, for every request |
| curl | --proxy with your URL |
| wget | the settings http_proxy and https_proxy |
| aria2c | --all-proxy with your URL |
| ffmpeg | the variable HTTP_PROXY, and SOCKS fails |
| axel, httpie | nothing |
Two details matter here. First, only the --proxy value is handed on. A proxy that yt-dlp found in the environment is not, and each program then follows its own rules. Second, yt-dlp hands more jobs to ffmpeg than its name suggests: live streams, cuts made with --download-sections, and some HLS streams. With a SOCKS proxy, yt-dlp warns: "ffmpeg does not support SOCKS proxies. Downloading is likely to fail." Give those jobs an http:// line.
Websocket downloads work the other way round. A few sites stream over websockets, and yt-dlp's websocket client takes only SOCKS proxies. With an http:// proxy those sites fail with "This request requires WebSocket support". A maintainer confirmed the cause in issue #9509: "the current websockets lib we have only supports socks proxy".
What does --geo-verification-proxy do?
It sends only the requests that an extractor marks as geo checks. For those requests it beats every other setting, NO_PROXY included. The download itself still goes through --proxy. About 33 extractors mark such requests, among them NBC, PBS, Rai, TV4 and Tubi. The YouTube extractor marks none, so the option changes nothing there. Use it when a site checks your country once and then serves the files from anywhere.
Two other options sound like proxies and are not. --xff only fakes a header that claims another address. --source-address picks which of your own addresses to use. For YouTube, one more detail: yt-dlp passes its YouTube proxy to PO token providers with each token request. A provider that fetches on its own can then use the same line.
Which proxy type fits yt-dlp?
Our server met YouTube's check on its first request, and a datacenter proxy also leaves from a hosting network. For YouTube, use a residential IP. Use a sticky line for each job, so the page, the API calls and the download leave from one IP. A rotating line can change IP between them. Expect an IP to wear out: one user saw the check vanish behind a proxy IP and return a few hours later (issue #14899). Start the next job on a fresh session.
A residential line bills per gigabyte, and the video file is the heavy part. Check the setup with --skip-download first, so the first test does not pull a whole video.
HProxy residential gateways fit this. Allow your server's IP on a Residential Premium plan, up to 150 per plan, and point --proxy at a sticky port with no password. An allowed IP takes no country or city targeting. When a job needs a country, use a generated line with the targeting in its username. A sticky line keeps one IP, but that IP can drop early if its device leaves the network, so let the job retry. The residential proxies page lists the plans, and the plan API generates lines and manages allowed IPs from code.
How do I check which proxy yt-dlp uses?
Run the job once with -v. The log prints a line that starts with "Proxy map", and it shows the proxy yt-dlp chose. Mask that line before you paste a log anywhere, because it prints the password too. We found one user's proxy login in a public issue that way. To see the IP a site gets, run curl --proxy "http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT" https://api.ipify.org with the same URL.
What breaks when the proxy is on?
- "To use an HTTPS proxy for this request..." You wrote
https://. Writehttp://, or install requests. - "This request requires WebSocket support". The site needs a websocket and your proxy is
http://. Use asocks5://line for that site. - "ffmpeg does not support SOCKS proxies". A live stream or a section cut went to ffmpeg. Use an
http://line. - HTTP Error 407. The proxy refused the login. On our gateways this means a wrong password or a line from another plan. Our 407 guide walks through it.
- The bot check stays behind the proxy. The IP still looks like a server, or it wore out. Move to a residential line and see the guide to the bot message for cookies.
- HTTP 403 when you run an old ffmpeg command again. The stream address expired. The maintainers said so in issue #11421. Run yt-dlp again for a fresh one.
- HTTP 412 from Bilibili. Our server got it on the first request, so volume is not the only trigger. Try a residential line.
What this page does not cover
We read yt-dlp's docs and code at release 2026.08.19 and did not run yt-dlp. The test used plain requests from one server IP, over one afternoon, with no residential comparison. yt-dlp asks YouTube through its API clients, which can answer differently from the watch page. The count of 33 extractors comes from a code search on the main branch, while the YouTube result was checked at the release. Whether each helper program also reads proxy variables by itself is that program's own business, and we did not test it. yt-dlp ships every few weeks, so we will read these settings again at the newest release by 19 October 2026.
Where to go from here
The guide to the bot message covers cookies, PO tokens and the wiki's advice. Proxies for YouTube covers proxy types and accounts. HTTP vs SOCKS5 explains the two proxy kinds, and SOCKS5 errors explained decodes their failures. The guides to proxies in curl and wget cover two of the helper programs.
Sources
- Network options, geo options, dependencies, configuration and downloaders. yt-dlp README, release 2026.08.19, 19 August 2026.
- YoutubeDL.py, utils/networking.py, networking/_urllib.py, _requests.py, _curlcffi.py, _websockets.py, socks.py, downloader/external.py, downloader/init.py, extractor/common.py and the YouTube extractor. yt-dlp source code, release 2026.08.19, read on 19 September 2026.
- urllib.request.getproxies. Python documentation, read on 19 September 2026.
- Issues #8627, #9509, #11421, #14899, #14830, #6885 and #10128. yt-dlp issue tracker, 2023 to 2025.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: plain GET requests to six video sites and one control, two runs from our server, with curl. Raw output is kept in the page's research folder.
