How to use a proxy with aiohttp

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Basic authenticated proxy

import asyncio
import aiohttp

PROXY = "http://USERNAME:PASSWORD@HOST:PORT"


async def main():
    timeout = aiohttp.ClientTimeout(total=30)
    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())

Put the credentials in the proxy URL. aiohttp 3.14 deprecates the separate proxy_auth argument and BasicAuth, while credentials in the URL work on old and new versions.

Concurrent requests on a rotating line

Rotation happens per connection. A rotating line gets a new IP when your client opens a new connection; requests sent through the same open HTTPS tunnel leave from the same IP. Requests that run at the same time use separate connections, so they get different IPs. To get a new IP even for requests sent one after another, close each connection after use with force_close=True.

import asyncio
import aiohttp

PROXY = "http://USERNAME:PASSWORD@HOST:PORT"  # rotating line
URLS = ["https://ipinfo.io/json"] * 5


async def fetch(session, url):
    async with session.get(url, proxy=PROXY) as resp:
        return (await resp.json())["ip"]


async def main():
    connector = aiohttp.TCPConnector(limit=10, force_close=True)  # new connection per request
    timeout = aiohttp.ClientTimeout(total=30)
    async with aiohttp.ClientSession(connector=connector, timeout=timeout) as session:
        print(await asyncio.gather(*(fetch(session, u) for u in URLS)))


asyncio.run(main())

limit caps how many connections run at once (the default is 100). Start low on protected sites.

Sticky lines per account or task

To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand. Pass the same sticky line as proxy= for every request that belongs to one account or task.

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them.

PROXY = "http://USERNAME-country-gb:PASSWORD@HOST:PORT"

SOCKS5 with aiohttp-socks

aiohttp’s proxy= takes HTTP proxies only. For SOCKS5, install aiohttp-socks and pass its connector to the session instead of a proxy= argument.

pip install aiohttp-socks

import asyncio
import aiohttp
from aiohttp_socks import ProxyConnector


async def main():
    connector = ProxyConnector.from_url("socks5://USERNAME:PASSWORD@HOST:SOCKS5_PORT")
    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())

For SOCKS5, aiohttp-socks resolves hostnames through the proxy by default (rdns=True).

Tips

• Reuse one ClientSession for the whole program; creating a session per request is slow and leaks connections.
• Set aiohttp.ClientTimeout so a stalled exit can’t hang your tasks.
• Use trust_env=True on the session if you want aiohttp to read HTTP_PROXY and HTTPS_PROXY.

Troubleshooting

• ClientHttpProxyError with status 407

  The proxy rejected the credentials. Check the line in the generator and URL-encode special characters.More on this error →

• A “Bad status line” or similar error when you pass a socks5:// URL to proxy=

  aiohttp’s proxy= only takes HTTP proxies. Use aiohttp_socks.ProxyConnector for SOCKS5.

• The IP doesn’t change on a rotating line

  Your client is reusing an open connection. Requests that share a tunnel share its IP. Open a new connection per request, or use one sticky line per task.More on this error →

• Timeouts

  Set an explicit timeout of 30–60 seconds, retry on a new connection, and lower concurrency.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions