Hide navigation sidebar
Hide table of contents sidebar
Support urllib3 on GitHub Sponsors
Back to top
Toggle table of contents sidebar

# SOCKS Proxies

This module contains provisional support for SOCKS proxies from within urllib3. This module supports SOCKS4, SOCKS4A (an extension of SOCKS4), and SOCKS5. To enable its functionality, either install PySocks or install this module with the `socks` extra.

The SOCKS implementation supports the full range of urllib3 features. It also supports the following SOCKS features:

- SOCKS4A (`proxy_url='socks4a://...`)

- SOCKS4 (`proxy_url='socks4://...`)

- SOCKS5 with remote DNS (`proxy_url='socks5h://...`)

- SOCKS5 with local DNS (`proxy_url='socks5://...`)

- Usernames and passwords for the SOCKS proxy

Note

It is recommended to use `socks5h://` or `socks4a://` schemes in your `proxy_url` to ensure that DNS resolution is done from the remote server instead of client-side when connecting to a domain name.

SOCKS4 supports IPv4 and domain names with the SOCKS4A extension. SOCKS5 supports IPv4, IPv6, and domain names.

When connecting to a SOCKS4 proxy the `username` portion of the `proxy_url` will be sent as the `userid` section of the SOCKS request:

    proxy_url="socks4a://<userid>@proxy-host"

When connecting to a SOCKS5 proxy the `username` and `password` portion of the `proxy_url` will be sent as the username/password to authenticate with the proxy:

    proxy_url="socks5h://<username>:<password>@proxy-host"

class urllib3.contrib.socks.SOCKSConnection(*args, **kwargs)

  Bases: `HTTPConnection`

  A plain-text HTTP connection that connects via a SOCKS proxy.

class urllib3.contrib.socks.SOCKSHTTPConnectionPool(host, port=None, strict=False, timeout=<object object>, maxsize=1, block=False, headers=None, retries=None, _proxy=None, _proxy_headers=None, _proxy_config=None, **conn_kw)

  Bases: `HTTPConnectionPool`

  ConnectionCls

    alias of `SOCKSConnection`

class urllib3.contrib.socks.SOCKSHTTPSConnection(*args, **kwargs)

  Bases: `SOCKSConnection`, `HTTPSConnection`

class urllib3.contrib.socks.SOCKSHTTPSConnectionPool(host, port=None, strict=False, timeout=<object object>, maxsize=1, block=False, headers=None, retries=None, _proxy=None, _proxy_headers=None, key_file=None, cert_file=None, cert_reqs=None, key_password=None, ca_certs=None, ssl_version=None, assert_hostname=None, assert_fingerprint=None, ca_cert_dir=None, **conn_kw)

  Bases: `HTTPSConnectionPool`

  ConnectionCls

    alias of `SOCKSHTTPSConnection`

class urllib3.contrib.socks.SOCKSProxyManager(proxy_url, username=None, password=None, num_pools=10, headers=None, **connection_pool_kw)

  Bases: `PoolManager`

  A version of the urllib3 ProxyManager that routes connections via the defined SOCKS proxy.

  pool_classes_by_scheme = {'http': <class 'urllib3.contrib.socks.SOCKSHTTPConnectionPool'>, 'https': <class 'urllib3.contrib.socks.SOCKSHTTPSConnectionPool'>}