{"id":1071,"date":"2026-10-12T17:37:40","date_gmt":"2026-10-12T14:37:40","guid":{"rendered":"https:\/\/mexela.com\/blog\/python-aiohttp-proxy\/"},"modified":"2026-10-13T20:19:37","modified_gmt":"2026-10-13T17:19:37","slug":"python-aiohttp-proxy","status":"publish","type":"post","link":"https:\/\/mexela.com\/blog\/python-aiohttp-proxy\/","title":{"rendered":"Python aiohttp Proxy Setup: Sessions, Authentication and Timeouts"},"content":{"rendered":"

For an aiohttp request, pass the HTTP proxy through session.get(..., proxy=proxy_url)<\/code>. Keep a session alive across related requests, set bounded timeouts, and verify the destination observation. aiohttp 3.14.5 was tested here; it ignores proxy environment variables by default.<\/p>\n

Reviewed and locally tested: October 12, 2026.<\/strong> Version and route observations below describe the stated test environment. A working local route does not establish a provider’s public exit, country, anonymity, speed, or uptime.<\/p>\n

Start with the tested version<\/h2>\n
python -m pip install "aiohttp==3.14.5"<\/code><\/pre>\n
The local tests ran with Python 3.12.14 on Windows. Check your application’s interpreter and dependency constraints before adopting the pin. HTTPX and aiohttp expose different proxy APIs: copying a client constructor from another library can create a plausible configuration that never affects the request.<\/p>\n
Make one request with explicit proxy and TLS settings<\/h2>\n
import asyncio, os, ssl\nimport aiohttp\n\ndef tls_context(ca_file=None):\n    return ssl.create_default_context(cafile=ca_file)\n\nasync def aiohttp_request(url, proxy_url=None, ca_file=None):\n    timeout=aiohttp.ClientTimeout(total=5, connect=2)\n    async with aiohttp.ClientSession(timeout=timeout, trust_env=False) as session:\n        async with session.get(url, proxy=proxy_url, ssl=tls_context(ca_file),\n                               allow_redirects=False) as response:\n            return response.status, await response.json()\n\nstatus, body = asyncio.run(aiohttp_request(\n    os.environ["CHECK_URL"], os.environ["PROXY_URL"]))\nprint({"status": status})<\/code><\/pre>\n
Use a trusted endpoint returning JSON, and supply credentials through an environment value or secret manager. This helper reads the body before leaving the response context. It does not treat a JSON response or successful status as proof of a public proxy exit; compare the destination’s recorded observation with the direct call using proxy_url=None<\/code>. Redirects are disabled to keep the check on one endpoint.<\/p>\n
The session in this small diagnostic closes after the request. In a long-running application, create one session for a suitable lifetime and pass it to request functions. The aiohttp client quickstart<\/a> explains response handling and connection reuse.<\/p>\n
Choose authentication for the installed release<\/h2>\n
The tested example uses a proxy URL containing username\/password credentials. Percent-encode each credential component and keep the resulting URL out of source control, logs and screenshots. Proxy authentication is separate from an API token used by the destination.<\/p>\n
from urllib.parse import quote\n\nproxy_url = "http:\/\/{}:{}@proxy.example:8080".format(\n    quote(os.environ["PROXY_USER"], safe=""),\n    quote(os.environ["PROXY_PASSWORD"], safe=""))<\/code><\/pre>\n
Current 3.14 documentation deprecates the older proxy_auth<\/code> argument, with removal planned for 4.0, and describes encode_basic_auth<\/code> with proxy_headers<\/code> for explicit headers. The URL form above was the form exercised in our fixture. For a migration, consult the installed version’s proxy support reference<\/a> rather than silently carrying older BasicAuth examples forward.<\/p>\n
Separate total and connection budgets<\/h2>\n
ClientTimeout(total=5, connect=2)<\/code> sets a total request budget and a connection budget. Pool waiting can affect the connection budget when many requests share a connector. A timeout does not tell you whether authentication was correct or whether the API would have accepted the request. Use the ClientTimeout reference<\/a> to choose values for your workload.<\/p>\n
Avoid retrying every exception immediately. A failed credential needs a configuration fix; a bounded transient connection failure may justify a limited retry; a destination rate limit needs the destination’s policy. Record a sanitized failure class and attempt count without printing the proxy URL.<\/p>\n
Enable environment inheritance only when you intend it<\/h2>\n
async with aiohttp.ClientSession(trust_env=True) as session:\n    async with session.get(os.environ["CHECK_URL"],\n                           timeout=aiohttp.ClientTimeout(total=5)) as response:\n        print({"status": response.status})<\/code><\/pre>\n
This is an alternative configuration path, not an addition to the explicit proxy helper. Our five-case matrix showed default sessions using the direct route, and sessions with trust_env=True<\/code> honoring the proxy and matching NO_PROXY rule. Read the environment-variable matrix<\/a> before applying shell-wide settings.<\/p>\n
Measured HTTP and CONNECT behavior<\/h2>\n\n\n\n\n\n\n\n\n
Case<\/th>\nLocal observation<\/th>\n<\/tr>\n<\/thead>\n
Authenticated HTTP proxy<\/td>\nOwned destination recorded the proxy route<\/td>\n<\/tr>\n
HTTPS through HTTP CONNECT<\/td>\nRequest passed with the disposable destination CA explicitly trusted<\/td>\n<\/tr>\n
Untrusted destination certificate<\/td>\nRequest rejected while certificate verification remained enabled<\/td>\n<\/tr>\n
Proxy credentials at destination<\/td>\nProxy-Authorization header absent<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
The fixture connected only to owned loopback endpoints. It did not test an HTTPS connection to the proxy itself, TLS-in-TLS, SOCKS support, commercial exits, or throughput. An HTTP proxy tunneling an HTTPS destination is a different case from an https:\/\/<\/code> proxy endpoint; verify your exact transport against the current support reference.<\/p>\n
Resolve the error at the responsible endpoint<\/h2>\n
A 407 points to proxy authentication; a destination 401 points to API authentication; a connection refusal points to reachability; a certificate failure points to trust or hostname validation. Confirm that all requests use the intended session. Compare HTTPX async setup<\/a> when choosing a client, and use the error checklist<\/a> for a repeatable incident record.<\/p>\n
Frequently asked questions<\/h2>\n
\n
Can I put proxy credentials in the destination Authorization header?<\/h3>\n
No. Destination Authorization authenticates to the API. Keep proxy credentials in the proxy configuration and the API token in the destination request configuration.<\/p>\n
Does a session route every request automatically?<\/h3>\n
Verify the configuration path used by each call. This guide supplies proxy= at request level, while environment inheritance is a separate, deliberate choice.<\/p>\n<\/div>\n
Verify one client before increasing workload<\/h2>\n
Return to Proxy Setup and Developer Guides<\/a> for adjacent clients. Use the proxy verification checklist<\/a> to record a direct baseline and the destination’s observation. When that is repeatable, compare Mexela proxy locations<\/a> against the actual destination and location requirements.<\/p>\n
<\/p>\n
Download the developer examples<\/h2>\n
Download the developer examples ZIP<\/a> for the locally tested Python clients, environment checks, CI route-check files and native PHP cURL helper. The n8n workflow is a separate illustrative reference: it was not imported or executed in n8n. Read the included README for runtime versions, setup and the limits of each check.<\/p>\n
ZIP SHA-256: 3a43f7d1e6cbb9b2917dbcf88aaa8fe1a2733c33326187cb89c9a9119aad3e20<\/code>. Keep real proxy credentials and destination secrets in your approved secret store; they are absent from this archive. Start with one approved destination and compare its observation with a direct baseline.<\/p>\n
<\/p>\n
Versioned Python aiohttp source files<\/h2>\n
Use the Python aiohttp folder in the public source repository<\/a> for the example, setup instructions, exact dependency versions and a sanitized test summary. The repository is a dated snapshot of owned examples; its loopback checks do not certify a commercial endpoint or every application configuration.<\/p>\n","protected":false},"excerpt":{"rendered":"
Use aiohttp request proxies with a reusable session, explicit timeouts and verified TLS. Includes current authentication changes and local route observations.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[189],"tags":[],"_links":{"self":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/1071"}],"collection":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/comments?post=1071"}],"version-history":[{"count":0,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/posts\/1071\/revisions"}],"wp:attachment":[{"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/media?parent=1071"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/categories?post=1071"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/mexela.com\/blog\/wp-json\/wp\/v2\/tags?post=1071"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}