Install & Compatibility
Where this runs
tested against v0.12.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.690s · 27.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.0s · import 0.622s · 30MB
27MB installed
● package 27MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ProxyConnector
✓ from aiohttp_socks import ProxyConnector
✗ from aiohttp_socks import SocksConnector
While `SocksConnector` might appear in older examples or versions, `ProxyConnector` is the current and recommended class for instantiating proxy connections.
ChainProxyConnector
✓ from aiohttp_socks import ChainProxyConnector
ProxyType
✓ from aiohttp_socks import ProxyType
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.
import aiohttp
import asyncio
import os
from aiohttp_socks import ProxyType, ProxyConnector
async def fetch_with_proxy(url):
# Get proxy URL from environment variable for security and flexibility
# Example: socks5://user:password@127.0.0.1:1080
proxy_url = os.environ.get('AIOHTTP_SOCKS_PROXY_URL', 'socks5://127.0.0.1:1080')
connector = ProxyConnector.from_url(proxy_url)
async with aiohttp.ClientSession(connector=connector) as session:
async with session.get(url) as response:
response.raise_for_status()
text = await response.text()
print(f"Fetched via proxy: {url}\nStatus: {response.status}\nContent snippet: {text[:200]}...")
async def main():
print("Attempting to fetch with proxy...")
await fetch_with_proxy('http://httpbin.org/ip') # Use a simple endpoint to show IP
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
gotchaFor 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`.fixWhen 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)`. affects: All versions
breaking`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.fixTo use different proxies for different requests, create a new `aiohttp.ClientSession` with a new `ProxyConnector` for each unique proxy configuration required.
affects: All versions
gotchaOlder documentation or examples might refer to `SocksConnector` for creating proxy connections. The current and recommended class is `ProxyConnector`.fixAlways use `from aiohttp_socks import ProxyConnector` and instantiate `ProxyConnector` or `ChainProxyConnector` for new code.
affects: <0.11.0 (historical), but still a common confusion point
breakingThe 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.fixEnsure your environment meets the minimum requirements: `Python >= 3.8` and `aiohttp >= 3.10.0`.
affects: <0.11.0, especially when `aiohttp` is older than 3.10.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiohttp'
The 'aiohttp' module is not installed or not accessible in the current Python environment.
fixEnsure 'aiohttp' is installed by running 'pip install aiohttp' in the appropriate environment.
ImportError: cannot import name 'ProxyConnector' from 'aiohttp_socks'
The 'ProxyConnector' class is not available in the 'aiohttp_socks' module, possibly due to an incorrect import statement or version mismatch.
fixVerify the correct import statement: 'from aiohttp_socks import ProxyConnector'. Ensure you are using a compatible version of 'aiohttp_socks'.
TypeError: __init__() got an unexpected keyword argument 'proxy_type'
The 'ProxyConnector' constructor does not accept a 'proxy_type' keyword argument, indicating a possible misuse of the constructor.
fixUse the 'ProxyConnector.from_url()' method to create a connector: 'connector = ProxyConnector.from_url("socks5://user:password@127.0.0.1:1080")'. aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 127.0.0.1:1080 ssl:default [Connect call failed ('127.0.0.1', 1080)]
The proxy server at 127.0.0.1:1080 is unreachable, possibly because it is not running or the address/port is incorrect.
fixEnsure the proxy server is running and accessible at the specified address and port.
ValueError: Invalid proxy URL 'socks5://user:password@127.0.0.1:1080'
The proxy URL provided is malformed or contains invalid components.
fixVerify the proxy URL format: 'socks5://user:password@127.0.0.1:1080'. Ensure all components are correct and properly formatted.
Upgrade
Version history
0.12.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
pythonrequiredRequired runtime environment
aiohttprequiredCore asynchronous HTTP client/server library
python-socksrequiredUnderlying library for proxy functionality