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

> Master youtube-dl proxy support with this guide. Learn to configure HTTP, HTTPS, and SOCKS proxies, source IP binding, and network settings for seamless downloads.

- Repository: [youtube-dl/youtube-dl](https://github.com/ytdl-org/youtube-dl)
- Tags: how-to-guide
- Published: 2026-02-25

---

**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`](https://github.com/ytdl-org/youtube-dl/blob/main/utils.py) and [`options.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/utils.py) at lines 5894-5907.

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/utils.py) line 5907).

The `YoutubeDLHTTPSHandler` detects this header and invokes `make_socks_conn_class` (defined in [`utils.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/socks.py), specifically using `sockssocket.setproxy` to establish the connection through the SOCKS server.

```bash
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.

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/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.

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) lines 1818-1825.

```bash

# 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`](https://github.com/ytdl-org/youtube-dl/blob/main/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.

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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.

```bash
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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/options.py) lines 3040-3053.

The extractor base class in [`youtube_dl/extractor/common.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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.

```bash

# 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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`.

```bash

# 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`](https://github.com/ytdl-org/youtube-dl/blob/main/utils.py).
- **SOCKS Implementation**: Pure-Python SOCKS support using `sockssocket` from [`socks.py`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/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`](https://github.com/ytdl-org/youtube-dl/blob/main/youtube_dl/downloader/external.py).