Guides

How to send requests through a proxy in Python: httpx and aiohttp

Synchronous and asynchronous requests through an HTTP proxy and SOCKS5 with a login and password in httpx and aiohttp.

What you need

The proxy is issued in the format host:port:login:password. Replace HOST, PORT, LOGIN and PASSWORD in the examples with your own values. Both libraries can take the login and password separately from the address, so percent-encoding of special characters is not required.

pip install httpx aiohttp

Library versions

The proxy parameter exists in current versions of httpx; the old proxies parameter was removed in version 0.28. In aiohttp the proxy_auth parameter has been deprecated since version 3.14 and will be removed in 4.0; proxy_headers with encode_basic_auth is used instead. On an older aiohttp, pass proxy_auth=aiohttp.BasicAuth(LOGIN, PASSWORD).

Example

httpx: the synchronous and asynchronous clients are set up the same way.

import asyncio

import httpx

# The login and password are passed separately from the address, no need to encode them.
# The proxy scheme is http:// even for HTTPS sites
proxy = httpx.Proxy("http://HOST:PORT", auth=("LOGIN", "PASSWORD"))

# Synchronous version
with httpx.Client(proxy=proxy, timeout=30) as client:
    print(client.get("https://api.ipify.org").text)


# Asynchronous version
async def main() -> None:
    async with httpx.AsyncClient(proxy=proxy, timeout=30) as client:
        response = await client.get("https://api.ipify.org")
        print(response.text)


asyncio.run(main())

aiohttp: the proxy address and the header with the credentials are passed with each request.

import asyncio

import aiohttp


async def main() -> None:
    # The Proxy-Authorization header is built from the login and password, no need to encode them
    proxy_headers = {"Proxy-Authorization": aiohttp.encode_basic_auth("LOGIN", "PASSWORD")}
    timeout = aiohttp.ClientTimeout(total=30)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.get(
            "https://api.ipify.org",
            proxy="http://HOST:PORT",
            proxy_headers=proxy_headers,
        ) as response:
            # The service returns the address the request came from
            print(await response.text())


asyncio.run(main())

If SOCKS5

httpx understands the socks5:// and socks5h:// schemes after the extra dependencies are installed. aiohttp does not support SOCKS itself; the third-party aiohttp-socks package is used for it.

pip install "httpx[socks]" aiohttp-socks

import asyncio

import aiohttp
import httpx
from aiohttp_socks import ProxyConnector, ProxyType

# httpx: the socks5h:// scheme leaves name resolution to the proxy itself
socks_proxy = httpx.Proxy("socks5h://HOST:SOCKS_PORT", auth=("LOGIN", "PASSWORD"))
with httpx.Client(proxy=socks_proxy, timeout=30) as client:
    print(client.get("https://api.ipify.org").text)


# aiohttp: the credentials are passed to the connector, not to the request
async def main() -> None:
    connector = ProxyConnector(
        proxy_type=ProxyType.SOCKS5,
        host="HOST",
        port=int("SOCKS_PORT"),
        username="LOGIN",
        password="PASSWORD",
        rdns=True,
    )
    async with aiohttp.ClientSession(connector=connector) as session:
        async with session.get("https://api.ipify.org") as response:
            print(await response.text())


asyncio.run(main())

Common errors

407 Proxy Authentication Required: wrong login or password. In aiohttp, check that proxy_headers is passed in the same call as proxy.
ConnectTimeout, ProxyError or asyncio.TimeoutError: check HOST and PORT, whether the SOCKS5 port was put into HTTP mode, and increase timeout.
Special characters in the password: when the login and password are passed as separate parameters (auth= and encode_basic_auth), nothing needs encoding. If you write them in the address (http://LOGIN:PASSWORD@HOST:PORT), encode them with urllib.parse.quote(value, safe='').
The https:// scheme in the proxy address: the issued proxy works over HTTP, so write http://HOST:PORT even for HTTPS sites.
TypeError: unexpected keyword argument proxies in httpx: in newer versions use proxy=.
An error about a missing socksio package: install httpx[socks].

Sources

Checked against the official documentation: October 2026. Program interfaces change: if item names differ, follow the documentation.

All guides are collected on the Guides page.

Find a proxy in the chat