Typing stubs for PySocks

Common errors

• GeneralProxyError: Connection closed unexpectedly

  cause The proxy server closed the connection prematurely, possibly due to network issues, software problems on the proxy, or invalid negotiation.
  fix Verify the proxy server's status, network connectivity, and ensure the proxy type (SOCKS4, SOCKS5, HTTP) is correctly specified. Check proxy server logs for more details.

• GeneralProxyError: Bad proxy type

  cause The `proxy_type` parameter provided to `set_proxy` or `set_default_proxy` was not one of the valid `socks.SOCKS4`, `socks.SOCKS5`, or `socks.HTTP` constants.
  fix Ensure you are using `socks.SOCKS4`, `socks.SOCKS5`, or `socks.HTTP` for the `proxy_type` argument. Double-check your proxy server's actual type.

• SOCKS5AuthError: Authentication is required

  cause You attempted to connect to a SOCKS5 proxy server that requires authentication, but no username and password were provided in `set_proxy` or `set_default_proxy`.
  fix Provide a valid `username` and `password` to the `set_proxy` or `set_default_proxy` function when connecting to an authenticated SOCKS5 proxy. Example: `socks.set_default_proxy(socks.SOCKS5, 'host', 9050, True, 'your_user', 'your_pass')`.

• GeneralProxyError: Sent invalid data

  cause The proxy server received unexpected or malformed data, indicating a potential mismatch in protocol or a non-compliant proxy.
  fix Confirm that the proxy server is indeed a SOCKS (or CONNECT-based HTTP) proxy and that its configuration matches the `proxy_type` you've specified. This can also happen if the proxy server is misconfigured or overloaded.

Warnings

• gotcha PySocks' `socks.set_default_proxy` globally monkey-patches `socket.socket`. While convenient, this can have unintended side effects on other parts of your application or libraries that also interact with the socket module directly. Consider using `requests` with its `proxies` argument for HTTP/HTTPS traffic, which uses PySocks internally in a less intrusive way, or manually creating `socks.socksocket` instances for fine-grained control.
  Fix: For HTTP/HTTPS traffic, use the `requests` library with its `proxies` dictionary (e.g., `proxies={'http': 'socks5://user:pass@host:port'}`). For other protocols, explicitly create and use `socks.socksocket` instances rather than global monkey-patching where possible.
• gotcha PySocks' native HTTP proxy support is limited to proxies that use CONNECT tunneling. For standard HTTP proxies, it is generally recommended to use the HTTP client's native proxy support (e.g., `requests`' `proxies` parameter or `urllib.request.ProxyHandler`).
  Fix: If connecting to an HTTP proxy that does not support CONNECT tunneling, use your HTTP client's built-in proxy configuration. For `requests`, this means using the `proxies` argument (e.g., `proxies={'http': 'http://user:pass@host:port'}`).
• gotcha When using `requests` with a SOCKS proxy, you might encounter issues with DNS resolution if the proxy URL uses `socks5://`. By default, `requests` may attempt local DNS resolution.
  Fix: To ensure remote DNS resolution (i.e., DNS resolution by the proxy server), use `socks5h://` in your proxy URL. Example: `proxies = {'http': 'socks5h://127.0.0.1:9050', 'https': 'socks5h://127.0.0.1:9050'}`.
• gotcha PySocks has limited support for IPv6. Attempting to use IPv6 addresses might lead to errors or unexpected behavior.
  Fix: Prefer IPv4 proxy addresses and target hosts when using PySocks. If IPv6 is essential, consider alternative proxy libraries or methods that explicitly support it.

Install

• pip install pysocks types-pysocks Install PySocks and its typing stubs

Imports

• socks
  wrong:

  from types_pysocks import socks

  correct:

  import socks

  Types-pysocks provides type hints for the 'socks' module, not a runtime module itself. You should import 'socks' from the actual PySocks library.
• set_default_proxy

  import socks
  socks.set_default_proxy(...)

  Access functions and classes directly from the 'socks' module after import.

Quickstart

This quickstart demonstrates how to configure PySocks to route `urllib.request` traffic through a SOCKS5 proxy. It first sets a global default proxy and then 'monkey-patches' the standard `socket.socket` to use PySocks' `socksocket`, ensuring all subsequent socket operations (like those by `urllib.request`) go through the proxy. Ensure you have a running SOCKS proxy at the specified address and port.

import socks
import socket
import urllib.request
import os

# --- Configuration for SOCKS proxy ---
# Replace with your proxy details
PROXY_TYPE = socks.SOCKS5 # or socks.SOCKS4, socks.HTTP
PROXY_ADDR = os.environ.get('SOCKS_PROXY_ADDR', '127.0.0.1')
PROXY_PORT = int(os.environ.get('SOCKS_PROXY_PORT', 9050))
PROXY_USERNAME = os.environ.get('SOCKS_PROXY_USER', '')
PROXY_PASSWORD = os.environ.get('SOCKS_PROXY_PASS', '')

# Set up the default proxy for all subsequent socket connections
if PROXY_USERNAME and PROXY_PASSWORD:
    socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT, True, PROXY_USERNAME, PROXY_PASSWORD)
else:
    socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT)

# "Monkey-patch" the socket module to use PySocks
socket.socket = socks.socksocket

try:
    # Make a request that will now go through the SOCKS proxy
    print(f"Attempting to fetch external IP via proxy {PROXY_ADDR}:{PROXY_PORT}...")
    with urllib.request.urlopen('http://icanhazip.com') as response:
        external_ip = response.read().decode('utf-8').strip()
        print(f"External IP (via proxy): {external_ip}")
except socks.ProxyError as e:
    print(f"Failed to connect via proxy: {e}")
except urllib.error.URLError as e:
    print(f"URL Error: {e.reason}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")