{"id":9378,"library":"types-pysocks","title":"Typing stubs for PySocks","description":"types-pysocks provides static type checking stubs for the PySocks library, enabling developers to write more robust and type-safe Python code when working with SOCKS proxy servers. PySocks itself is a Python module that offers a straightforward interface for routing network traffic through SOCKS proxies. The types-pysocks package, maintained by the Python community's typeshed project, keeps its stubs updated to reflect the PySocks API, with version 1.7.1.20260408 currently supporting Python 3.10 and newer. While the underlying PySocks library's direct development cadence might vary, the types-pysocks stubs are actively maintained.","status":"active","version":"1.7.1.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","pysocks","proxy","socks","typeshed","networking"],"install":[{"cmd":"pip install pysocks types-pysocks","lang":"bash","label":"Install PySocks and its typing stubs"}],"dependencies":[{"reason":"Provides the runtime functionality for which these stubs offer type hints.","package":"pysocks"}],"imports":[{"note":"Types-pysocks provides type hints for the 'socks' module, not a runtime module itself. You should import 'socks' from the actual PySocks library.","wrong":"from types_pysocks import socks","symbol":"socks","correct":"import socks"},{"note":"Access functions and classes directly from the 'socks' module after import.","symbol":"set_default_proxy","correct":"import socks\nsocks.set_default_proxy(...)"}],"quickstart":{"code":"import socks\nimport socket\nimport urllib.request\nimport os\n\n# --- Configuration for SOCKS proxy ---\n# Replace with your proxy details\nPROXY_TYPE = socks.SOCKS5 # or socks.SOCKS4, socks.HTTP\nPROXY_ADDR = os.environ.get('SOCKS_PROXY_ADDR', '127.0.0.1')\nPROXY_PORT = int(os.environ.get('SOCKS_PROXY_PORT', 9050))\nPROXY_USERNAME = os.environ.get('SOCKS_PROXY_USER', '')\nPROXY_PASSWORD = os.environ.get('SOCKS_PROXY_PASS', '')\n\n# Set up the default proxy for all subsequent socket connections\nif PROXY_USERNAME and PROXY_PASSWORD:\n    socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT, True, PROXY_USERNAME, PROXY_PASSWORD)\nelse:\n    socks.set_default_proxy(PROXY_TYPE, PROXY_ADDR, PROXY_PORT)\n\n# \"Monkey-patch\" the socket module to use PySocks\nsocket.socket = socks.socksocket\n\ntry:\n    # Make a request that will now go through the SOCKS proxy\n    print(f\"Attempting to fetch external IP via proxy {PROXY_ADDR}:{PROXY_PORT}...\")\n    with urllib.request.urlopen('http://icanhazip.com') as response:\n        external_ip = response.read().decode('utf-8').strip()\n        print(f\"External IP (via proxy): {external_ip}\")\nexcept socks.ProxyError as e:\n    print(f\"Failed to connect via proxy: {e}\")\nexcept urllib.error.URLError as e:\n    print(f\"URL Error: {e.reason}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of PySocks"},{"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'}`).","message":"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`).","severity":"gotcha","affected_versions":"All versions of PySocks"},{"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'}`.","message":"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.","severity":"gotcha","affected_versions":"All versions of PySocks when used with `requests`"},{"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.","message":"PySocks has limited support for IPv6. Attempting to use IPv6 addresses might lead to errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions of PySocks"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The proxy server closed the connection prematurely, possibly due to network issues, software problems on the proxy, or invalid negotiation.","error":"GeneralProxyError: Connection closed unexpectedly"},{"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.","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.","error":"GeneralProxyError: Bad proxy type"},{"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')`.","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`.","error":"SOCKS5AuthError: Authentication is required"},{"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.","cause":"The proxy server received unexpected or malformed data, indicating a potential mismatch in protocol or a non-compliant proxy.","error":"GeneralProxyError: Sent invalid data"}]}