youtube-dl Proxy Support Options and Network Configuration: A Complete Guide

youtube-dl supports HTTP, HTTPS, and SOCKS proxies via the --proxy flag, along with source IP binding, IPv4/IPv6 forcing, socket timeouts, and separate geo-verification proxies, all implemented through custom request handlers in utils.py and options.py.

The ytdl-org/youtube-dl repository implements a comprehensive network stack that routes traffic through various proxy types while providing fine-grained control over network interfaces and connection parameters. Understanding these proxy support options and network configuration capabilities is essential for users operating behind corporate firewalls, accessing geo-restricted content, or managing multi-homed systems.

Core Proxy Configuration Options

HTTP and HTTPS Proxies (--proxy)

The primary method for routing traffic through a proxy uses the --proxy option, defined in youtube_dl/options.py at lines 200-208. This option accepts URLs with http://, https://, or socks:// schemes.

When a request is initiated, YoutubeDLHTTPSHandler (and its HTTP counterpart) intercepts the request and adds a temporary header Ytdl-request-proxy if a proxy is configured. This header triggers the custom proxy handling logic located in youtube_dl/utils.py at lines 5894-5907.

youtube-dl --proxy http://proxy.example.com:3128 "https://www.youtube.com/watch?v=abcd"

SOCKS Proxy Support (SOCKS4/4a/5)

youtube-dl provides native SOCKS support without requiring external dependencies. When the proxy URL uses socks4, socks4a, or socks5 schemes, the request handler adds the header Ytdl-socks-proxy (see utils.py line 5907).

The YoutubeDLHTTPSHandler detects this header and invokes make_socks_conn_class (defined in utils.py lines 2867-2890) to dynamically create a subclass of HTTPConnection or HTTPSConnection. This subclass utilizes the pure-Python SOCKS implementation found in youtube_dl/socks.py, specifically using sockssocket.setproxy to establish the connection through the SOCKS server.

youtube-dl --proxy socks5://127.0.0.1:1080 "https://vimeo.com/12345"

Disabling Proxies for Direct Connections

To force a direct connection without proxying, pass an empty string to the --proxy option. This is interpreted as "no proxy" and causes the handler to skip all proxy-related header injection and connection setup.

youtube-dl --proxy "" "https://www.dailymotion.com/video/x7y8z9"

Advanced Network Configuration

Source Address Binding (--source-address)

For systems with multiple network interfaces or IP addresses, youtube-dl supports binding to a specific source IP address. This option is defined in youtube_dl/options.py at lines 2013-2016. The specified address is passed to urllib.request.Request via the source_address attribute of the underlying socket.

youtube-dl --source-address 192.168.1.100 "https://www.twitch.tv/example"

IPv4 and IPv6 Enforcement (-4 and -6)

The -4 and -6 flags provide convenient shortcuts for forcing IPv4 or IPv6 connections. Internally, these set the source_address parameter to 0.0.0.0 (for IPv4) or :: (for IPv6) respectively, as implemented in youtube_dl/options.py lines 1818-1825.

# Force IPv4 only

youtube-dl -4 "https://www.youtube.com/watch?v=efgh"

# Force IPv6 only

youtube-dl -6 "https://www.youtube.com/watch?v=efgh"

Socket Timeouts (--socket-timeout)

Network timeout behavior is configurable via --socket-timeout, defined in youtube_dl/options.py lines 2009-2011. The value is stored in params['socket_timeout'] and subsequently passed to the underlying http.client.HTTPConnection objects, controlling how long the client waits for server responses.

youtube-dl --socket-timeout 30 "https://example.com/video"

Geo-Verification and Geo-Bypass Proxies

Separate Geo-Verification Proxy (--geo-verification-proxy)

Certain extractors require verifying the client's external IP address without routing the actual download traffic through that proxy. The --geo-verification-proxy option (defined in youtube_dl/options.py lines 3029-3033) addresses this need.

When IP verification is required, the extractor adds the header Ytdl-request-proxy (see youtube_dl/utils.py lines 3330-3333), which triggers the same proxy machinery as the standard --proxy option but only for the verification request. The main download stream continues to use the primary proxy configuration.

youtube-dl \
  --proxy http://main-proxy:8080 \
  --geo-verification-proxy http://geo-proxy:8080 \
  "https://www.netflix.com/watch/80192062"

Geo-Restriction Bypass Methods (--geo-bypass)

For content restricted by geography, youtube-dl provides several geo-bypass mechanisms that manipulate the X-Forwarded-For header to simulate different geographic locations. These options are defined in youtube_dl/options.py lines 3040-3053.

The extractor base class in youtube_dl/extractor/common.py (lines 3330-3340) implements the logic to inject the X-Forwarded-For header based on the specified country code or IP block, potentially bypassing geographic restrictions without requiring a proxy.

# Bypass using a specific country code

youtube-dl --geo-bypass-country US "https://www.hulu.com/watch/123456"

# Bypass using a specific IP range

youtube-dl --geo-bypass-ip-block 203.0.113.0/24 "https://example.com/video"

External Downloader Integration

Passing Proxy Settings to ffmpeg and aria2c

When using external downloaders such as ffmpeg or aria2c, youtube-dl propagates proxy settings through environment variables. This logic is implemented in youtube_dl/downloader/external.py at lines 423-439.

The external downloader wrapper sets HTTP_PROXY and http_proxy environment variables before spawning the child process, ensuring that external tools respect the same proxy configuration specified via --proxy.

# Using aria2c with proxy settings

youtube-dl --proxy http://proxy:8080 --external-downloader aria2c "https://example.com/video"

Summary

• HTTP/HTTPS/SOCKS Support: Route all traffic through --proxy with support for http, https, socks4, socks4a, and socks5 schemes via custom handlers in utils.py.
• SOCKS Implementation: Pure-Python SOCKS support using sockssocket from socks.py and connection class generation via make_socks_conn_class.
• Network Binding: Bind to specific interfaces using --source-address or force IP versions with -4 and -6 flags.
• Timeout Control: Configure connection timeouts with --socket-timeout passed to underlying HTTP connections.
• Geo-Specific Proxies: Use --geo-verification-proxy for IP verification only, or bypass geo-restrictions with --geo-bypass and X-Forwarded-For headers.
• External Tool Integration: Proxy settings propagate to ffmpeg and aria2c via environment variables in external.py.

Frequently Asked Questions

How do I configure youtube-dl to use a SOCKS5 proxy?

Use the --proxy option with a socks5:// scheme. For example: youtube-dl --proxy socks5://127.0.0.1:1080 "URL". The tool detects the SOCKS scheme and uses the pure-Python implementation in youtube_dl/socks.py to route connections through the proxy without requiring external dependencies.

What is the difference between --proxy and --geo-verification-proxy?

The --proxy option routes all download traffic through the specified server, while --geo-verification-proxy is used only for IP verification requests that certain extractors perform to check your apparent geographic location. This allows you to route verification traffic through a specific proxy while keeping the main download on your primary connection or a different proxy.

How can I force youtube-dl to use IPv4 only?

Use the -4 flag, which is a shortcut that sets the source address to 0.0.0.0. Alternatively, use --source-address followed by a specific IPv4 address on your system. Both methods are defined in youtube_dl/options.py and affect the underlying socket binding.

Does youtube-dl pass proxy settings to external downloaders like ffmpeg?

Yes. When using external downloaders such as ffmpeg or aria2c, youtube-dl sets the HTTP_PROXY and http_proxy environment variables before spawning the subprocess. This ensures external tools respect the proxy configuration specified via the --proxy option, as implemented in youtube_dl/downloader/external.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}