{"id":2245,"library":"python-socks","title":"Python-Socks","description":"The python-socks package provides a core proxy client functionality for Python. It supports SOCKS4(a), SOCKS5(h), and HTTP CONNECT proxies, offering both synchronous and asynchronous (asyncio, trio, curio, anyio) APIs. It's often used internally by other HTTP client libraries like `aiohttp-socks` and `httpx-socks` rather than directly. The current version is 2.8.1, and it maintains an active release cadence.","status":"active","version":"2.8.1","language":"en","source_language":"en","source_url":"https://github.com/romis2012/python-socks","tags":["proxy","socks","networking","asyncio","trio","curio","anyio"],"install":[{"cmd":"pip install python-socks","lang":"bash","label":"Sync support"},{"cmd":"pip install python-socks[asyncio]","lang":"bash","label":"Asyncio support"},{"cmd":"pip install python-socks[trio]","lang":"bash","label":"Trio support"},{"cmd":"pip install python-socks[curio]","lang":"bash","label":"Curio support"},{"cmd":"pip install python-socks[anyio]","lang":"bash","label":"AnyIO support"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"Python","optional":false},{"reason":"Optional, required for asyncio backend >= 4.0.","package":"async-timeout","optional":true},{"reason":"Optional, required for trio backend >= 0.24.","package":"trio","optional":true},{"reason":"Optional, required for curio backend >= 1.4.","package":"curio","optional":true},{"reason":"Optional, required for anyio backend >= 3.3.4.","package":"anyio","optional":true}],"imports":[{"symbol":"Proxy (sync)","correct":"from python_socks.sync import Proxy"},{"symbol":"Proxy (asyncio)","correct":"from python_socks.async_.asyncio import Proxy"}],"quickstart":{"code":"import ssl\nimport os\nfrom python_socks.sync import Proxy\n\n# Get proxy URL from environment variable, e.g., \"socks5://user:password@127.0.0.1:1080\"\nproxy_url = os.environ.get('PYTHON_SOCKS_PROXY_URL', 'socks5://127.0.0.1:1080')\n\ntry:\n    proxy = Proxy.from_url(proxy_url)\n\n    # `connect` returns standard Python socket in blocking mode\n    sock = proxy.connect(dest_host='check-host.net', dest_port=443)\n    \n    # Wrap socket for SSL/TLS if connecting to HTTPS\n    sock = ssl.create_default_context().wrap_socket(\n        sock=sock,\n        server_hostname='check-host.net'\n    )\n    \n    request = (\n        b'GET /ip HTTP/1.1\\r\\n'\n        b'Host: check-host.net\\r\\n'\n        b'Connection: close\\r\\n\\r\\n'\n    )\n    \n    sock.sendall(request)\n    \n    response_parts = []\n    while True:\n        data = sock.recv(4096)\n        if not data:\n            break\n        response_parts.append(data)\n    \n    full_response = b\"\".join(response_parts)\n    print(\"Received response through proxy:\")\n    print(full_response.decode('utf-8', errors='ignore'))\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Ensure a SOCKS proxy is running and PYTHON_SOCKS_PROXY_URL environment variable is set correctly.\")\n    print(\"Example: export PYTHON_SOCKS_PROXY_URL=\\\"socks5://user:pass@127.0.0.1:1080\\\"\")\n\nfinally:\n    if 'sock' in locals() and sock:\n        sock.close()","lang":"python","description":"This quickstart demonstrates how to establish a synchronous connection through a SOCKS5 proxy to fetch the IP address from `check-host.net`. The proxy URL is retrieved from the `PYTHON_SOCKS_PROXY_URL` environment variable for secure credential handling. It includes SSL/TLS wrapping for HTTPS connections."},"warnings":[{"fix":"Consider using `aiohttp-socks` for aiohttp or `httpx-socks` for httpx if you are primarily proxying HTTP/HTTPS traffic.","message":"Many users might try to use `python-socks` directly for HTTP/HTTPS proxying when higher-level libraries like `aiohttp-socks` or `httpx-socks` (which use `python-socks` internally) offer a more convenient and integrated API for common use cases.","severity":"gotcha","affected_versions":"All"},{"fix":"Always use `socks5h://` in your proxy URL if you want DNS resolution to happen on the proxy server for improved privacy and reliability.","message":"Using `socks5://` (local DNS resolution) instead of `socks5h://` (remote DNS resolution on the proxy) can lead to DNS leaks or failures if the proxy network requires remote DNS for hostname resolution.","severity":"gotcha","affected_versions":"All"},{"fix":"Install the specific optional dependency for your chosen async backend: `pip install python-socks[asyncio]`, `pip install python-socks[trio]`, etc.","message":"Attempting to use `python-socks` with an async backend (e.g., asyncio, trio) without installing the corresponding optional dependency (e.g., `pip install python-socks[asyncio]`) will result in `ImportError` or `ModuleNotFoundError`.","severity":"breaking","affected_versions":"All"},{"fix":"Ensure your project is running on Python 3.8 or a later version.","message":"This library explicitly requires Python 3.8 or newer. Using it with older Python versions will lead to syntax errors or compatibility issues.","severity":"breaking","affected_versions":"<3.8"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}