aiohttp_socks

aiohttp-socks

The aiohttp-socks package provides a proxy connector for aiohttp. Supports SOCKS4(a), SOCKS5(h), HTTP (CONNECT) as well as Proxy chains. It uses python-socks for core proxy functionality.

Requirements

Python >= 3.8
aiohttp >= 3.10.0
python-socks[asyncio] >= 2.4.3

Installation

pip install aiohttp_socks

Usage

Simple usage

import aiohttp
from aiohttp_socks import ProxyType, ProxyConnector, ChainProxyConnector


async def fetch(url):
    connector = ProxyConnector.from_url('socks5://user:password@127.0.0.1:1080')
    
    ### or use ProxyConnector constructor
    # connector = ProxyConnector(
    #     proxy_type=ProxyType.SOCKS5,
    #     host='127.0.0.1',
    #     port=1080,
    #     username='user',
    #     password='password',
    #     rdns=True # default is True for socks5
    # )
    
    ### proxy chaining (since ver 0.3.3)
    # connector = ChainProxyConnector.from_urls([
    #     'socks5://user:password@127.0.0.1:1080',
    #     'socks4://127.0.0.1:1081',
    #     'http://user:password@127.0.0.1:3128',
    # ])
    async with aiohttp.ClientSession(connector=connector) as session:
        async with session.get(url) as response:
            return await response.text()

Exception handling recommendations

Since the latest versions of aiohttp do not respect exceptions raised in the custom TCPConnector (see issue #52), the following pattern can be used to handle ProxyConnectionError and ProxyTimeoutError exceptions

from aiohttp_socks import (
    ProxyConnectionError,
    ProxyTimeoutError,
)

def is_proxy_connection_error(e: Exception):
    return isinstance(e, ProxyConnectionError) or isinstance(
        e.__cause__, ProxyConnectionError
    )


def is_proxy_timeout_error(e: Exception):
    return isinstance(e, ProxyTimeoutError) or isinstance(
        e.__cause__, ProxyTimeoutError
    )


try:
    await fetch(...)
except Exception as e:
    if is_proxy_connection_error(e):
        ...do something  useful...

Why yet another SOCKS connector for aiohttp

Unlike aiosocksy, aiohttp_socks has only single point of integration with aiohttp. This makes it easier to maintain compatibility with new aiohttp versions.

Metadata

Release files for aiohttp_socks 0.10.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiohttp_socks 0.10.2
File	Size	Uploaded
aiohttp_socks-0.10.2.tar.gz	11.3 kB	Nov 10, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for aiohttp_socks 0.10.2
File	Interpreter	ABI	Platform	Reset
aiohttp_socks-0.10.2-py3-none-any.whl 10.5 kB Nov 10, 2025	Python 3	none	any	Details

Total release size: 21.8 kB

Release files / aiohttp_socks-0.10.2.tar.gz

Download URL	aiohttp_socks-0.10.2.tar.gz
Size	11.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`942d7c86e2e579418fc7a734610dd97daaf00707c7462f6ccf679b2325767930`
BLAKE2b-256 checksum How to use checksums	`75071598f292433bcdceb069515811ba5221034f4f12535d06c3372a1b71a785`
Upload date	Nov 10, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.11.5`

Release files / aiohttp_socks-0.10.2-py3-none-any.whl

Download URL	aiohttp_socks-0.10.2-py3-none-any.whl
Size	10.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`84b29d14356bcda4affa03ef267108416390e1c9029922c66be18ef4b106f980`
BLAKE2b-256 checksum How to use checksums	`7f51906d2ef2e9dfe2f3e76e53696f2d73c508f99b54c05d7e9acd8e7033d505`
Upload date	Nov 10, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.11.5`