{"id":2856,"library":"aiohttp-socks","title":"Proxy connector for aiohttp","description":"The `aiohttp-socks` package extends `aiohttp` by providing a proxy connector. It supports SOCKS4(a), SOCKS5(h), and HTTP (CONNECT) proxies, as well as proxy chaining, by leveraging the `python-socks` library for core proxy functionality. The current version is 0.11.0 and it maintains compatibility with recent `aiohttp` versions.","status":"active","version":"0.11.0","language":"en","source_language":"en","source_url":"https://github.com/romis2012/aiohttp-socks","tags":["asyncio","aiohttp","socks","socks5","socks4","http","proxy"],"install":[{"cmd":"pip install aiohttp-socks","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required runtime environment","package":"python","version":">=3.8"},{"reason":"Core asynchronous HTTP client/server library","package":"aiohttp","version":">=3.10.0"},{"reason":"Underlying library for proxy functionality","package":"python-socks","version":">=2.4.3","optional":false}],"imports":[{"note":"While `SocksConnector` might appear in older examples or versions, `ProxyConnector` is the current and recommended class for instantiating proxy connections.","wrong":"from aiohttp_socks import SocksConnector","symbol":"ProxyConnector","correct":"from aiohttp_socks import ProxyConnector"},{"symbol":"ChainProxyConnector","correct":"from aiohttp_socks import ChainProxyConnector"},{"symbol":"ProxyType","correct":"from aiohttp_socks import ProxyType"}],"quickstart":{"code":"import aiohttp\nimport asyncio\nimport os\nfrom aiohttp_socks import ProxyType, ProxyConnector\n\nasync def fetch_with_proxy(url):\n    # Get proxy URL from environment variable for security and flexibility\n    # Example: socks5://user:password@127.0.0.1:1080\n    proxy_url = os.environ.get('AIOHTTP_SOCKS_PROXY_URL', 'socks5://127.0.0.1:1080')\n    \n    connector = ProxyConnector.from_url(proxy_url)\n    \n    async with aiohttp.ClientSession(connector=connector) as session:\n        async with session.get(url) as response:\n            response.raise_for_status()\n            text = await response.text()\n            print(f\"Fetched via proxy: {url}\\nStatus: {response.status}\\nContent snippet: {text[:200]}...\")\n\nasync def main():\n    print(\"Attempting to fetch with proxy...\")\n    await fetch_with_proxy('http://httpbin.org/ip') # Use a simple endpoint to show IP\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to configure an `aiohttp.ClientSession` to route requests through a SOCKS5 proxy using `ProxyConnector.from_url`. The proxy URL is retrieved from an environment variable for safe credentials handling. Ensure a proxy server is running at the specified address and port."},"warnings":[{"fix":"When using `ProxyConnector.from_url('socks5://...')`, change to `ProxyConnector.from_url('socks5h://...')`. Alternatively, when using the constructor, ensure `rdns=True` is set: `ProxyConnector(proxy_type=ProxyType.SOCKS5, host='...', port=..., rdns=True)`.","message":"For SOCKS5 proxies, if connection issues (e.g., 'Connection refused') occur, ensure reverse DNS (rDNS) is enabled. This can be done by passing `rdns=True` to the `ProxyConnector` constructor or by using the `socks5h://` scheme in the proxy URL for `from_url`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To use different proxies for different requests, create a new `aiohttp.ClientSession` with a new `ProxyConnector` for each unique proxy configuration required.","message":"`aiohttp-socks` does not support setting a different proxy per request within a single `aiohttp.ClientSession`. The `ProxyConnector` is static for the session it's attached to. Attempting to pass a `proxy` argument to `session.get()` or similar methods will bypass `aiohttp-socks` or not work as expected.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always use `from aiohttp_socks import ProxyConnector` and instantiate `ProxyConnector` or `ChainProxyConnector` for new code.","message":"Older documentation or examples might refer to `SocksConnector` for creating proxy connections. The current and recommended class is `ProxyConnector`.","severity":"gotcha","affected_versions":"<0.11.0 (historical), but still a common confusion point"},{"fix":"Ensure your environment meets the minimum requirements: `Python >= 3.8` and `aiohttp >= 3.10.0`.","message":"The minimum required Python version is 3.8 and `aiohttp` must be at least version 3.10.0. Using older versions can lead to `ImportError` or runtime incompatibilities.","severity":"breaking","affected_versions":"<0.11.0, especially when `aiohttp` is older than 3.10.0"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}