Skip to content

Python httpx and aiohttp Proxy: Sync and Async Examples

Copy-ready httpx and aiohttp code for an HTTP proxy with a login, and the six things that differ between the two libraries.

The setup in one line each

httpx takes the proxy when you create the client: httpx.Client(proxy=URL) or httpx.AsyncClient(proxy=URL), with the login written in the URL as user:password@host:port. aiohttp takes it per request: session.get(url, proxy=URL), and the same URL form with credentials works there too.

Use the HTTP address of your proxy (port 2222 on Proxy302) in both. A password with characters such as @ or : must be percent-encoded in the URL, for example with urllib.parse.quote.

httpx and aiohttp side by side

httpx and aiohttp side by side
Itemhttpxaiohttp
Where the proxy goesproxy= on Client or AsyncClientproxy= on each request
LoginIn the URL: user:password@host:portIn the URL, or as headers for the proxy
Environment variablesUsed by default; trust_env=False turns them offIgnored by default; trust_env=True turns them on
SOCKS5pip install httpx[socks], then a socks5:// URLNot covered by aiohttp; the third-party aiohttp-socks package adds a connector
Default timeoutTimeoutException after 5 seconds of inactivity300 seconds in total, 30 seconds to connect

From the HTTPX and aiohttp documentation and the aiohttp-socks README read on 16 November 2026.

httpx, synchronous

import httpx

PROXY = "http://LOGIN:PASSWORD@HOST:2222"

with httpx.Client(proxy=PROXY, timeout=httpx.Timeout(20.0, connect=10.0)) as client:
    print(client.get("https://ipinfo.io/json").json())

Example only: replace LOGIN, PASSWORD and HOST with the values from My assets.

httpx, asynchronous, with a cap on parallel requests

import asyncio
import httpx

PROXY = "http://LOGIN:PASSWORD@HOST:2222"

async def fetch(client, sem, url):
    async with sem:
        r = await client.get(url)
        return r.status_code

async def main(urls):
    sem = asyncio.Semaphore(10)  # your own cap on parallel requests
    async with httpx.AsyncClient(proxy=PROXY, timeout=20.0) as client:
        print(await asyncio.gather(*(fetch(client, sem, u) for u in urls)))

asyncio.run(main(["https://ipinfo.io/json"] * 3))

Example only: the semaphore is your own limit; tune it to what the target site accepts.

aiohttp

import asyncio
import aiohttp

PROXY = "http://LOGIN:PASSWORD@HOST:2222"

async def main():
    timeout = aiohttp.ClientTimeout(total=30, connect=10)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.get("https://ipinfo.io/json", proxy=PROXY) as resp:
            print(await resp.json())

asyncio.run(main())

Example only: the proxy goes on the request, the timeout on the session.

SOCKS5 with httpx and aiohttp

# pip install "httpx[socks]" aiohttp_socks
import asyncio
import aiohttp
import httpx
from aiohttp_socks import ProxyConnector

SOCKS = "socks5://LOGIN:PASSWORD@HOST:3333"

# httpx
with httpx.Client(proxy=SOCKS) as client:
    print(client.get("https://ipinfo.io/json").json())

# aiohttp: SOCKS goes through a connector, not the proxy= argument
async def main():
    connector = ProxyConnector.from_url(SOCKS)
    async with aiohttp.ClientSession(connector=connector) as session:
        async with session.get("https://ipinfo.io/json") as resp:
            print(await resp.json())

asyncio.run(main())

Example only: port 3333 is SOCKS5 on Proxy302; HTTP on 2222 needs no extra package.

Six pitfalls

1. Old tutorials use proxies=; the current httpx documentation shows proxy= and mounts, so use those. 2. If HTTP_PROXY is set on your machine or in the container, httpx uses it without being asked, and aiohttp ignores it unless you pass trust_env=True. 3. SOCKS5 needs httpx[socks] for httpx and aiohttp-socks for aiohttp.

4. Timeouts differ: set them explicitly in both libraries so one slow request does not decide how long a job runs. 5. A client or session keeps connections alive, and a rotating line gives a new IP per new connection, so one reused connection keeps one IP. 6. Opening a new client for every request throws away connection reuse; reuse one client and create new ones only when you want a new IP.

Which Proxy302 product for a script

A script that must always come from the same address, for example to call an API that allowlists your IP, needs a fixed IP: a static ISP IP is US$0.50 for 1 day and US$7.99 for 30 days, a datacenter IP is US$0.25 for 1 day and US$3.99 for 30 days. Both keep the same IP during the lease.

A collection job that wants many exits fits rotating residential traffic: US$1.50 per GB on the Budget line, US$5 per GB on the Premium line, with no limit on concurrent connections on the dynamic lines. Rotating datacenter proxies cost US$0.40 per GB and exit in the US only. There is no free trial.

Set it up and check the exit in 5 steps

  1. Step 1: Choose HTTP

    Buy the IP with HTTP selected, or use rotating residential on its HTTP port 2222, and copy HOST, PORT, USERNAME and PASSWORD from My assets.

  2. Step 2: Test with curl

    Run curl -x http://LOGIN:PASSWORD@HOST:2222 https://ipinfo.io/json first.

    Expected result JSON with the proxy's IP and country.

  3. Step 3: Run the httpx or aiohttp example

    Fill in the three values and run it.

    Expected result The same IP as the curl test.

  4. Step 4: Set timeouts and a cap

    Add explicit timeouts and, for async code, a semaphore.

  5. Step 5: Point it at the target

    Replace ipinfo.io only after the exit matches.

If it does not work

httpx.ProxyError or ConnectError

Check Host, port and that you used an http:// address on port 2222.

Fix Fix the URL; test the same URL with curl.

Stop when curl fails too: check your network and the address in My assets.

407 Proxy Authentication Required

Check The login in the URL, especially special characters.

Fix Percent-encode the password and copy the login again.

Stop when Same result in curl: open a ticket with the order number.

aiohttp ignores the proxy you set in the environment

Check trust_env is False by default.

Fix Pass proxy= on the request, or create the session with trust_env=True.

Stop when Still no proxy: print the exit IP and compare with curl.

ReadTimeout with httpx, or a hang in aiohttp

Check The default timeouts: 5 seconds of inactivity in httpx, 300 seconds in total in aiohttp.

Fix Set explicit timeouts and add a short retry with a pause.

Stop when Every request times out: test the proxy with curl before changing the code.

Every request has the same IP

Check A reused client or session keeps its connection alive.

Fix Use a new client for a new IP, or choose a rotating line and several connections.

Stop when You need one IP on purpose: choose a sticky session or a static IP.

httpx and aiohttp proxy FAQ

How do I use a proxy with httpx?

Pass proxy="http://LOGIN:PASSWORD@HOST:PORT" to httpx.Client or httpx.AsyncClient.

How do I use a proxy with aiohttp?

Pass proxy="http://LOGIN:PASSWORD@HOST:PORT" to session.get or any other request method of an aiohttp.ClientSession.

Does aiohttp support SOCKS5?

The aiohttp documentation covers HTTP proxies. For SOCKS5 the third-party aiohttp-socks package provides a ProxyConnector.

Why does httpx use a proxy I did not set?

httpx reads HTTP_PROXY, HTTPS_PROXY and ALL_PROXY by default; pass trust_env=False to turn that off.

How many parallel requests can I send?

The dynamic lines do not limit concurrent connections, but the site you call may. Cap your own concurrency with a semaphore.

Reference links

7
  1. HTTPX: Proxies

    Official documentation · Confirmed on:

    Read 16 November 2026: the proxy parameter on Client and top-level functions; credentials in the URL userinfo; mounts for routing HTTP and HTTPS to different proxies; SOCKS needs pip install httpx[socks] and a socks5:// URL. The page documents proxy and mounts only.

  2. HTTPX: Environment variables

    Official documentation · Confirmed on:

    Read 16 November 2026: HTTP_PROXY, HTTPS_PROXY and ALL_PROXY set the proxy, NO_PROXY disables it for specific URLs; environment variables are used by default and trust_env=False turns that off.

  3. HTTPX: Timeouts

    Official documentation · Confirmed on:

    Read 16 November 2026: the default is a TimeoutException after 5 seconds of network inactivity; connect, read, write and pool timeouts; httpx.Timeout(10.0, connect=60.0).

  4. aiohttp: Advanced client usage

    Official documentation · Confirmed on:

    Read 16 November 2026: proxy= takes a URL, supporting plain HTTP proxies and HTTP proxies upgraded to HTTPS with CONNECT; credentials can be given in the proxy URL; aiohttp does not read proxy environment variables by default and trust_env=True enables it; limited support for proxies reached over https://; SOCKS is not mentioned.

  5. aiohttp: Client reference

    Official documentation · Confirmed on:

    Read 16 November 2026: the default ClientSession timeout is 300 seconds in total with a 30-second socket connect timeout; trust_env is False by default.

  6. aiohttp-socks on GitHub

    Third-party source · Confirmed on:

    Read 16 November 2026: pip install aiohttp_socks; ProxyConnector.from_url("socks5://user:[email protected]:1080"); supports SOCKS4, SOCKS5 and HTTP CONNECT proxies. A third-party package, not part of aiohttp.

  7. Proxy302 product facts and price list

    Product observation · Confirmed on:

    Product facts file of the site, checked 16 November 2026: prices in US$ (1 PTC = US$1), lease terms, protocols and ports (HTTP 2222, SOCKS5 3333), what each product connects over, countries and city targeting, no free trial.

Ready to try it?

Create an account, top up once, then pick rotating residential, static ISP or datacenter IPs and have one running in your browser within minutes.