Proxy connector for aiohttp

0.11.0 verified Sat Apr 25 auth: no python

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.

pip install aiohttp-socks

Common errors

error ModuleNotFoundError: No module named 'aiohttp' ↓

cause The 'aiohttp' module is not installed or not accessible in the current Python environment.

fix

Ensure 'aiohttp' is installed by running 'pip install aiohttp' in the appropriate environment.

error ImportError: cannot import name 'ProxyConnector' from 'aiohttp_socks' ↓

cause The 'ProxyConnector' class is not available in the 'aiohttp_socks' module, possibly due to an incorrect import statement or version mismatch.

fix

Verify the correct import statement: 'from aiohttp_socks import ProxyConnector'. Ensure you are using a compatible version of 'aiohttp_socks'.

error TypeError: __init__() got an unexpected keyword argument 'proxy_type' ↓

cause The 'ProxyConnector' constructor does not accept a 'proxy_type' keyword argument, indicating a possible misuse of the constructor.

fix

Use the 'ProxyConnector.from_url()' method to create a connector: 'connector = ProxyConnector.from_url("socks5://user:password@127.0.0.1:1080")'.

error aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host 127.0.0.1:1080 ssl:default [Connect call failed ('127.0.0.1', 1080)] ↓

cause The proxy server at 127.0.0.1:1080 is unreachable, possibly because it is not running or the address/port is incorrect.

fix

Ensure the proxy server is running and accessible at the specified address and port.

error ValueError: Invalid proxy URL 'socks5://user:password@127.0.0.1:1080' ↓

cause The proxy URL provided is malformed or contains invalid components.

fix

Verify the proxy URL format: 'socks5://user:password@127.0.0.1:1080'. Ensure all components are correct and properly formatted.

Warnings

gotcha 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`. ↓

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)`.

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. ↓

fix To use different proxies for different requests, create a new `aiohttp.ClientSession` with a new `ProxyConnector` for each unique proxy configuration required.

gotcha Older documentation or examples might refer to `SocksConnector` for creating proxy connections. The current and recommended class is `ProxyConnector`. ↓

fix Always use `from aiohttp_socks import ProxyConnector` and instantiate `ProxyConnector` or `ChainProxyConnector` for new code.

breaking 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. ↓

fix Ensure your environment meets the minimum requirements: `Python >= 3.8` and `aiohttp >= 3.10.0`.

Install compatibility last tested: 2026-04-25

runtime status import time mem disk

3.10-alpine 0.54s 14.3MB 28.2M

3.10-slim 0.50s 14.3MB 30M

3.11-alpine 0.82s 15.2MB 30.9M

3.11-slim 0.72s 15.2MB 33M

3.12-alpine 0.94s 15.6MB 22.8M

3.12-slim 1.20s 15.6MB 25M

3.13-alpine 0.86s 15.7MB 22.0M

3.13-slim 1.08s 15.7MB 24M

3.9-alpine 0.53s 13.8MB 28.1M

3.9-slim 0.54s 13.8MB 31M

Imports

ProxyConnector
wrong
```
from aiohttp_socks import SocksConnector
```
correct
```
from aiohttp_socks import ProxyConnector
```
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
```

Quickstart last tested: 2026-04-25

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())