aiohttp proxy: auth, trust_env, SOCKS5, limits and rotation
Set a proxy in Python aiohttp: proxy= per session or request, auth after the 3.14 proxy_auth deprecation, trust_env, SOCKS5, connector limits and each error.

Quick summary · TL;DR
- Pass the proxy as proxy= and keep http:// even for HTTPS sites. ClientSession(proxy="http://USERNAME:PASSWORD@HOST:PORT") covers both, a proxy= on one get() overrides it, and the session form needs aiohttp 3.11 or later, so run pip show aiohttp before copying an old tutorial.
- If your password has a /, # or ? in it, percent-encode it, or you get InvalidURL with the password printed in the message. Skip proxy_auth=BasicAuth(...) too: it warns on every call since 3.14, and its proxy_headers replacement works per request only and does nothing for plain-HTTP targets.
- HTTPS_PROXY does nothing until you pass trust_env=True, and even then ALL_PROXY is skipped and an https:// value in HTTPS_PROXY is dropped with a log warning, so requests go direct without an error. An explicit proxy= saves you that hunt.
- On an HTTPS site a 407 arrives as ClientHttpProxyError, not a status code, and because it subclasses ClientResponseError you catch it first; only plain http:// targets give you resp.status == 407.
- For SOCKS5 you need aiohttp-socks, which rejects socks5h://. ProxyConnector.from_url("socks5://...") already sends the hostname to the proxy by default; rdns=False is what turns that off.
To use an aiohttp proxy, pass the proxy URL as proxy=: on the session with aiohttp.ClientSession(proxy="http://USERNAME:PASSWORD@HOST:PORT"), or on one call with session.get(url, proxy=...). The URL keeps the http:// scheme even for HTTPS sites. aiohttp ignores HTTP_PROXY and HTTPS_PROXY unless the session has trust_env=True, and SOCKS5 needs the separate aiohttp-socks package.
That gets the first request out. The trouble starts later, and most of it does not look like a proxy problem: a DeprecationWarning about proxy_auth after an upgrade, a 407 that arrives as an exception instead of a status code, an environment proxy that works for curl and is silently skipped by aiohttp, a job that stalls at exactly 100 open tunnels. Each one comes from how aiohttp builds connections, and each has a fix below.
Every snippet is written for aiohttp 3.14.5, and the proxy-facing ones were run against a local test proxy. Placeholders stand in for real credentials: HOST, PORT, USERNAME, PASSWORD.
aiohttp proxy setup, the short version
Read the proxy URL from the environment yourself, set a timeout you chose on purpose, and check the exit IP before anything else runs:
import asyncio
import os
import aiohttp
PROXY = os.environ["PROXY_URL"] # http://USERNAME:PASSWORD@HOST:PORT
async def main():
timeout = aiohttp.ClientTimeout(total=60, sock_connect=10)
async with aiohttp.ClientSession(proxy=PROXY, timeout=timeout) as session:
async with session.get("https://httpbingo.org/ip") as resp:
print(await resp.json())
asyncio.run(main())
The session-level proxy= arrived in aiohttp 3.11.0 (2024-11-13), according to the aiohttp changelog. On older versions only the per-request form works, which is why so many tutorials pass proxy= on every get(). Both still work, and a per-request proxy= overrides the session default for that call. That pays off once you get to rotation, since httpx has no per-request proxy and aiohttp does.
Watch the default timeout, it is generous. A session without timeout= gets ClientTimeout(total=300, sock_connect=30), five minutes per request. A hung request through a dead exit holds its slot that long, so set total to what one request should take, plus the proxy hop.
Which aiohttp version you have
On PyPI (checked 2026-11-04), aiohttp 3.14.5, uploaded 2026-10-11, is current. Run pip show aiohttp first, because the version decides whether the session-level proxy exists (3.11+) and whether proxy_auth warns (3.14+). An SDK built on aiohttp that ignores your proxy created its own session; pass yours in if it accepts one.
Proxy URL scheme and authentication
http:// for HTTPS targets
For an HTTPS site, aiohttp connects to the proxy over plain TCP and sends CONNECT site:443. The proxy opens a tunnel and TLS runs end to end between your script and the site, so the proxy relays encrypted bytes it cannot read. The aiohttp proxy docs describe exactly this: plain HTTP proxies, and HTTP proxies “upgraded to HTTPS via the HTTP CONNECT method”. That is why the proxy URL stays http:// for HTTPS traffic.
An https:// proxy URL means TLS to the proxy itself, then TLS to the site inside it. Against a proxy port that speaks plain HTTP, the handshake never completes and the request ends in a TimeoutError once your timeout runs out. With the default five-minute timeout that looks like a hang, which is the confusing part.
A URL with no scheme, such as HOST:8080, raises aiohttp.client_exceptions.InvalidURL. A socks5:// URL is not rejected at all: aiohttp speaks HTTP to the SOCKS port, reads back a SOCKS greeting, and raises ClientResponseError: 400, message="Bad status line". If you see that error with a SOCKS URL, the fix is the SOCKS section below, not the proxy.
Credentials and special characters
Credentials go in the userinfo part of the URL, and aiohttp turns them into a Proxy-Authorization header. An @ or : inside the password happens to parse. A /, # or ? does not, because yarl splits the URL at that character and aiohttp raises InvalidURL with your password printed in the message, which is the annoying part if it lands in a shared log. Percent-encode both parts:
import os
from urllib.parse import quote
user = quote(os.environ["PROXY_USER"], safe="")
password = quote(os.environ["PROXY_PASS"], safe="")
PROXY = f"http://{user}:{password}@HOST:PORT"
This form works for HTTPS and plain-HTTP targets alike, on the session or per request, and raises no warning on 3.14.5. It is the one to standardise on.
proxy_auth after the 3.14 deprecation
Most aiohttp proxy authentication examples pass proxy_auth=aiohttp.BasicAuth(user, password). Since 3.14.0 (2026-06-01) that raises a warning on every call:
DeprecationWarning: The 'proxy_auth' parameter is deprecated and will be removed in v4; pass proxy_headers={'Proxy-Authorization': aiohttp.encode_basic_auth(login, password)} instead
BasicAuth itself is deprecated too, and both disappear in aiohttp 4.0. The suggested replacement has two catches the warning does not mention, both checked on 3.14.5:
ClientSessiontakes noproxy_headers. The docs show a session built withproxy_headers=, and on 3.14.5 that line raisesTypeError: ClientSession.__init__() got an unexpected keyword argument 'proxy_headers'. Passproxy_headerson each request instead.proxy_headersonly reaches the proxy on the CONNECT. For HTTPS targets the header goes out with the tunnel request and the proxy accepts it. For a plainhttp://target the header is not sent, and the proxy answers 407.
encode_basic_auth() also defaults to UTF-8, where BasicAuth used latin1, so a password with non-ASCII characters can encode differently after the switch. And a : in the login raises ValueError in both. Credentials in a percent-encoded URL avoid all of this, which is why the URL form above is the safer default.
407 is an exception on HTTPS
When the proxy rejects the credentials, what aiohttp returns depends on the target’s scheme. For an HTTPS site the proxy refuses the CONNECT, no response from the site exists, and aiohttp raises ClientHttpProxyError: 407, message='Proxy Authentication Required'. Only a plain http:// target, which the proxy forwards, comes back as a response with resp.status == 407. So a status check on HTTPS traffic never sees it:
try:
async with session.get("https://httpbingo.org/ip") as resp:
print(await resp.json())
except aiohttp.ClientHttpProxyError as exc:
print("proxy refused the tunnel:", exc.status) # 407: encoding, wrong login, lapsed plan
ClientHttpProxyError is a subclass of ClientResponseError, so a broad except ClientResponseError swallows it together with ordinary HTTP errors. Catch it first. If you are on 3.13.2 or older and the 407 shows up only on the second request of a session, upgrade: 3.13.3 (2026-01-03) fixed proxy authorization headers being dropped when a connection was reused. The other causes of a 407 with known-good credentials are covered in 407 Proxy Authentication Required.
Environment variables and trust_env
aiohttp does not read proxy variables by default. The docs say it directly: “Contrary to the requests library, it won’t read environment variables by default”. So a script that works in Python requests with a proxy goes direct in aiohttp on the same machine, with no error. Pass trust_env=True to the session to change that:
async with aiohttp.ClientSession(trust_env=True) as session:
...
With trust_env=True, aiohttp reads the variables through urllib.request.getproxies() and applies them per URL scheme. On 3.14.5 against a local proxy, these held:
HTTPS_PROXYcovershttps://URLs andHTTP_PROXYcovershttp://URLs. A machine that only setsHTTP_PROXYsends every HTTPS request direct.ALL_PROXYis ignored. curl honours it, aiohttp does not.- An
https://value inHTTPS_PROXYis dropped. aiohttp logsHTTPS proxies https://... are not supported, ignoringand the request goes direct. Easy to miss if nobody reads warnings. NO_PROXYbypasses matching hosts, and credentials can come from~/.netrcwhen the URL has none.WS_PROXYandWSS_PROXYcover WebSockets.- An explicit
proxy=wins. Withproxy=set on the request or the session, the environment is not consulted.
On a CI runner or corporate laptop with its own https_proxy and no_proxy, trust_env=True hands those the routing. For a job that must leave through one known exit, set proxy= explicitly and leave trust_env off, which is the default anyway.
SOCKS5 with aiohttp-socks
Core aiohttp has no SOCKS support. An aiohttp SOCKS5 proxy goes through a connector from aiohttp-socks (0.12.0 of 2026-08-12 on PyPI, checked 2026-11-04), installed with pip install aiohttp-socks:
import aiohttp
from aiohttp_socks import ProxyConnector
connector = ProxyConnector.from_url("socks5://USERNAME:PASSWORD@HOST:PORT")
async with aiohttp.ClientSession(connector=connector) as session:
async with session.get("https://httpbingo.org/ip") as resp:
print(await resp.json())
Here the connector owns the proxy, so do not pass proxy= as well: one connector means one SOCKS proxy for the whole session. A few details trip people up:
- The hostname goes to the proxy by default. The connector skips local DNS, and python-socks turns remote resolution on for SOCKS5 when
rdnsis left unset. One ranking guide says remote DNS has to be switched on withrdns=True; on aiohttp-socks 0.12.0 with python-socks 3.2.1, the local test SOCKS5 server received the hostname with the default settings and an IP address only withrdns=False. Mechanics and a leak test are in DNS leak through a proxy. socks5h://is rejected. curl and requests use it for remote DNS, but aiohttp-socks raisesValueError: Invalid scheme component: socks5h. Writesocks5://.- Percent-encoded credentials are decoded, so the
quote(..., safe="")pattern from the HTTP section works here too. - The older
aiohttp-proxypackage ranks for the same search, but its last PyPI release, 0.1.2, dates from 2020-02-04. aiohttp-socks is the one with 2026 releases. - Failures have their own classes:
aiohttp_socks.ProxyError: Username and password authentication failurefor a wrong login,aiohttp_socks.ProxyConnectionErrorfor a port that does not answer.
proxymint’s per-GB gateway accepts SOCKS5 with the hostname sent to the proxy, and names resolve on the proxy side (proxymint Lab, measured 2026-09-28). When the choice is still open, SOCKS5 vs HTTP proxy covers what the protocol changes.
Connector limits and keep-alive
Concurrency is where an aiohttp proxy job usually breaks. A typical one looks like this:
import asyncio
import os
import aiohttp
PROXY = os.environ["PROXY_URL"]
LIMIT = 20 # concurrent tunnels this job opens
async def fetch(session, sem, url):
async with sem:
async with session.get(url) as resp:
resp.raise_for_status()
return await resp.text()
async def main(urls):
connector = aiohttp.TCPConnector(limit=LIMIT)
timeout = aiohttp.ClientTimeout(total=60, sock_connect=10)
sem = asyncio.Semaphore(LIMIT)
async with aiohttp.ClientSession(proxy=PROXY, connector=connector, timeout=timeout) as session:
return await asyncio.gather(*(fetch(session, sem, u) for u in urls), return_exceptions=True)
One request, one tunnel
HTTP/1.1 carries one request at a time per connection, and aiohttp’s client speaks HTTP/1.1. Through an HTTP proxy, every HTTPS connection is its own CONNECT tunnel, so 50 requests in flight means 50 tunnels to the proxy port. The client reference sets limit=100 and limit_per_host=0 on the connector, and in the local test 150 concurrent requests opened exactly 100 tunnels.
Watch out for limit_per_host. It sounds like the knob for a proxy port, but the connection key is the target host, not the proxy. With limit_per_host=2 and two target hosts behind one proxy, the test proxy saw four tunnels. To cap what one proxy port receives, set limit on a connector used only for that proxy. Size it to what the plan and the target both tolerate.
Keep-alive through proxies has been on since 3.11.0. Sequential requests on one session reuse one tunnel, an idle tunnel closes after 15 seconds, and the next request opens a new one. It saves a CONNECT and a TLS handshake per request, and it matters for rotation. Proxy performance tuning works through the latency arithmetic.
When the pool runs out
aiohttp has no separate pool timeout error. A request waiting for a free connection is already inside its total timeout, so when slow exits hold every slot, requests at the back of the queue fail with TimeoutError without ever reaching the proxy. In a local test with limit=1, total=3 and a target that took 2 seconds, the first request finished and the next two timed out at 3 seconds. The semaphore in the snippet fixes that: requests wait in your code, where no timer runs, and only LIMIT of them ever enter the pool. Keep the semaphore and limit at the same number so the job has one value to tune.
Rotating proxies with aiohttp
Because proxy= works per request, aiohttp proxy rotation can happen in your code, behind one gateway URL, or both.
An endpoint list. Several fixed proxies, such as a set of datacenter IPv4 addresses, each with its own username and password. Pass a different proxy= per request with itertools.cycle, or build one session per endpoint. Each distinct proxy URL gets its own pool entries, so alternating two URLs on one session opened two tunnels in the test, not one per request. One catch: a session has one cookie jar, so per-request rotation on a shared session sends the same cookies from every exit. When identities must stay apart, use one session per endpoint.
import itertools
PROXIES = [line.strip() for line in open("proxies.txt") if line.strip()] # one encoded http:// URL per line
pool = itertools.cycle(PROXIES)
async def fetch(session, sem, url):
async with sem:
async with session.get(url, proxy=next(pool)) as resp:
return resp.status, await resp.text()
itertools.cycle spreads the load evenly, where the random.choice most tutorials show can hit one endpoint three times in a row. Pass the ssl setting the same way on every call, too: the connection key includes it, so a new SSLContext per request quietly turns off connection reuse.
A rotating gateway. One proxy URL, and the provider changes the exit behind it. On proxymint’s rotating residential proxies, rotation is set on the order: a new IP on every request, a timer from 5 to 60 minutes, or sticky for as long as the device stays online, and it can be changed later without new credentials.
Keep-alive can pin the exit. A session reuses an open tunnel for the next request to the same host. If a gateway picks the exit when a connection opens, every call on that tunnel leaves from the same address, even on an order set to a new IP per request. TCPConnector(force_close=True) closes the connection after each request, so each one opens a new tunnel. Whether a gateway rotates per HTTP request or per new connection is a property of the provider, and the test below settles it in a minute.
Verify the exit IP
Run this before a job and on a sample during it. It compares the direct IP with the proxied ones, and a reused session with forced new connections:
import asyncio
import os
import aiohttp
PROXY = os.environ["PROXY_URL"]
ECHO = "https://httpbingo.org/ip"
async def origin(session):
async with session.get(ECHO) as resp:
return (await resp.json())["origin"]
async def main():
async with aiohttp.ClientSession() as direct: # trust_env is off by default
home = await origin(direct)
async with aiohttp.ClientSession(proxy=PROXY) as session:
reused = [await origin(session) for _ in range(5)]
connector = aiohttp.TCPConnector(force_close=True)
async with aiohttp.ClientSession(proxy=PROXY, connector=connector) as session:
fresh = [await origin(session) for _ in range(5)]
assert home not in reused + fresh, "a request left from the local IP"
print("reused:", reused)
print("fresh: ", fresh)
asyncio.run(main())
The assertion catches a silent bypass. If reused repeats one address while fresh changes, rotation follows new connections. If both change, the gateway rotates per request. On a sticky order both lists should show one address.
aiohttp proxy errors and retries
Most failures raise a specific exception; the silent ones, at the end of the table, do the most damage. Every row was reproduced on aiohttp 3.14.5 and aiohttp-socks 0.12.0 against a local proxy:
| What you see | Cause | Fix |
|---|---|---|
InvalidURL: http://user:p@ss/... | /, # or ? in an unencoded password, or no scheme | quote(..., safe=""), full http:// URL |
ClientHttpProxyError: 407, message='Proxy Authentication Required' | Rejected credentials on an HTTPS target | Check the encoding and the plan’s status |
resp.status == 407 | Rejected credentials on a plain-HTTP target, or proxy_headers used there | Credentials in the proxy URL |
ClientProxyConnectionError: Cannot connect to host | Proxy host or port unreachable, or egress blocked | Test the port from the same machine |
ClientResponseError: 400, message="Bad status line" | socks5:// URL passed to core aiohttp | ProxyConnector.from_url() from aiohttp-socks |
ValueError: Invalid scheme component: socks5h | socks5h:// in aiohttp-socks | Write socks5://; the hostname still goes to the proxy |
TimeoutError after the full timeout | https:// proxy URL on a plain-HTTP port, or a queue for the pool | http:// proxy scheme; semaphore sized to limit |
DeprecationWarning: The 'proxy_auth' parameter is deprecated | proxy_auth=BasicAuth(...) on 3.14+ | Percent-encoded credentials in the URL |
TypeError: ... unexpected keyword argument 'proxy_headers' | proxy_headers passed to ClientSession | Pass it per request, or use URL credentials |
| No error, local IP at the target | No trust_env=True, ALL_PROXY only, or an https:// HTTPS_PROXY | Set proxy= explicitly and check the exit IP |
Redirects are followed. aiohttp follows up to 10 redirects by default, and that matters behind proxymint’s per-GB gateway, which answers plain-HTTP requests with a 301 to the https:// address (the Lab page above, measured 2026-09-28). An http:// health check therefore returns the HTTPS page with the 301 in resp.history. It works, and pointing checks at https:// URLs saves the extra round trip.
aiohttp has no built-in retry. Retries belong in the job:
import asyncio
import random
import aiohttp
RETRY_STATUS = {429, 500, 502, 503, 504}
RETRY_ERRORS = (aiohttp.ClientProxyConnectionError, aiohttp.ServerDisconnectedError, asyncio.TimeoutError)
async def get_with_retry(session, url, attempts=4):
for attempt in range(attempts):
last = attempt == attempts - 1
try:
async with session.get(url) as resp:
if resp.status not in RETRY_STATUS or last:
return resp.status, await resp.text()
except RETRY_ERRORS:
if last:
raise
await asyncio.sleep(2 ** attempt + random.random())
ClientHttpProxyError is left out on purpose, since a 407 does not fix itself and a 403 is a refusal the job should respect. On a per-GB plan every retry also downloads the page again, so a 30% retry rate adds 30% to the traffic.
Choosing the proxy type
The aiohttp proxy code is the same for every category. The target and the job decide which one goes behind it:
- The job polls APIs or collects from targets without anti-bot scoring, at high concurrency. Datacenter proxies are built for that volume: IPv4 ports billed monthly with no bandwidth cap under normal use, each IP with its own username and password and an HTTP and a SOCKS5 port. Use the endpoint-list model, one connector per port, and tune
limitper port. What datacenter proxies are covers where hosting ranges are accepted. - The target scores hosting networks or shows home users different content. Rotating residential proxies serve consumer-origin coverage. Use one gateway URL and decide per job whether connection reuse should pin the exit.
- One login has to hold for days. Static ISP proxies keep one ISP-registered address for the billing term. Pin the job to one session.
- The platform expects a phone. Mobile proxies on carrier networks cover app-first platforms and mobile ad checks.
Whichever it is, keep three lines in every aiohttp job: an explicit proxy= with percent-encoded credentials, a semaphore that matches the connector’s limit, and an exit-IP check before the run.
Frequently asked questions
Pass the proxy URL as proxy, either on the session with aiohttp.ClientSession(proxy="http://USERNAME:PASSWORD@HOST:PORT") or on one call with session.get(url, proxy=...). The session-level argument needs aiohttp 3.11 or later; the per-request one works on every 3.x release. The URL keeps the http:// scheme for HTTPS sites, because aiohttp opens a CONNECT tunnel and TLS runs end to end.
Put the username and password in the proxy URL and percent-encode both with urllib.parse.quote(value, safe=""), since a /, # or ? in a raw password raises InvalidURL. This works for HTTPS and plain-HTTP targets without warnings on aiohttp 3.14.5. The alternative, proxy_headers with aiohttp.encode_basic_auth(), is accepted per request only and is not sent for plain-HTTP targets.
Yes. aiohttp 3.14.0, released on 2026-06-01, deprecated BasicAuth and the proxy_auth parameter, and both are due to be removed in aiohttp 4.0. Every call that passes proxy_auth raises a DeprecationWarning. Credentials in a percent-encoded proxy URL avoid the warning and keep working on both target schemes.
aiohttp only reads proxy environment variables when the session is created with trust_env=True, unlike requests and curl. With it on, HTTPS_PROXY applies to https:// URLs and HTTP_PROXY to http:// URLs, ALL_PROXY is ignored, and an https:// value in HTTPS_PROXY is dropped with a logged warning. An explicit proxy argument always wins over the environment.
Not in core aiohttp: a socks5:// URL passed as proxy is spoken to as HTTP and fails with a Bad status line error. Install aiohttp-socks and pass ProxyConnector.from_url("socks5://USERNAME:PASSWORD@HOST:PORT") as the session's connector. The hostname is sent to the proxy by default, and the socks5h:// scheme raises ValueError in aiohttp-socks.
The proxy refused the CONNECT tunnel for an HTTPS target, usually because of wrong or badly encoded credentials, proxy_headers on a session that does not accept them, or a plan that is no longer active. aiohttp raises ClientHttpProxyError with status 407 because no response from the site exists. Versions before 3.13.3 could also drop proxy credentials on reused connections, which produced 407s on later requests.
Either pass a different proxy URL per request from a list, or use one rotating gateway URL and let the provider change the exit. With a gateway, a reused keep-alive tunnel can keep the same exit, so TCPConnector(force_close=True) gives each request a new tunnel when every request should get a new IP. Use one session per identity when cookies must not travel between exits.
Researched and drafted with AI tools, then checked against our publishing rules before it went live: 5 outside links, 9 links to other proxymint pages, no prices and a fact-check pass against our product records. How we write.
