Routing Python httpx traffic through an authenticated proxy

· Updated:

To use an httpx proxy, pass the proxy URL when you create the client: httpx.Client(proxy="http://USER:PASS@IP:PORT"). Credentials ride in the URL, the same argument works on httpx.AsyncClient, and SOCKS5 needs one extra install. The proxies= argument that older tutorials show was removed in httpx 0.28, which is why copied snippets now fail with a TypeError.

A static IP that drops into Client(proxy=...)

The minimal working client

httpx attaches proxies to the client, not to individual calls. Build the client once with proxy=, then reuse it for every request so the connection to the proxy stays open between calls.

import httpx

PROXY = "http://USER:[email protected]:8080"

with httpx.Client(proxy=PROXY, timeout=15.0) as client:
    r = client.get("https://proxyv4.com/api/my-ip")
    print(r.status_code, r.json())

Note the scheme of the proxy URL. It stays http:// even though the target is https://. httpx sends a CONNECT request to the proxy, the proxy opens a raw tunnel, and TLS to the website runs inside it. Changing the proxy scheme to https:// asks httpx to speak TLS to the proxy itself, which a standard proxy port does not accept.

If your provider hands you lines in ip:port:user:pass form, rewrite them as http://user:pass@ip:port. The proxy format converter does a whole list at once.

proxies= is gone: migrating to httpx 0.28

httpx 0.26 introduced the singular proxy= argument and deprecated the old proxies= dictionary. Version 0.28 removed proxies= entirely, so code such as httpx.Client(proxies={"all://": url}) raises TypeError: Client.__init__() got an unexpected keyword argument 'proxies'.

The migration depends on what the old dictionary did:

  • One proxy for everything: replace the dictionary with proxy=url.
  • Different proxies per scheme or per host: move each entry to mounts=, wrapping the URL in httpx.HTTPTransport(proxy=url) (or httpx.AsyncHTTPTransport for async clients).
  • Per-request proxies: httpx never supported a proxy= keyword on client.get(). Keep one client per proxy and choose the client per request.

httpx proxy authentication in detail

Basic proxy authentication is the only scheme most commercial proxies use, and httpx handles it without extra code. It reads the user and password from the URL and adds a Proxy-Authorization header to the forwarded request or to the CONNECT request.

Passwords with reserved characters

A password containing @, :, / or # breaks URL parsing, and the symptom is usually a confusing connection error to the wrong host. Percent-encode both parts before you build the string:

from urllib.parse import quote

user, password = "USER", "p@ss:word/1"
proxy_url = f"http://{quote(user, safe='')}:{quote(password, safe='')}@203.0.113.10:8080"

Keeping credentials out of the URL

If you would rather not log a URL that contains a secret, use an httpx.Proxy object and pass the credentials separately. This keeps the printable URL clean and lets you load the password from a secrets store.

import os
import httpx

proxy = httpx.Proxy(
    "http://203.0.113.10:8080",
    auth=(os.environ["PROXY_USER"], os.environ["PROXY_PASS"]),
)
client = httpx.Client(proxy=proxy)

Per-host routing with mounts

mounts maps URL patterns to transports. The most specific pattern wins, so you can send one domain through a dedicated IP, send everything else through a second IP, and keep internal hosts direct.

import httpx

mounts = {
    "all://": httpx.HTTPTransport(proxy="http://USER:[email protected]:8080"),
    "all://*.example.com": httpx.HTTPTransport(proxy="http://USER:[email protected]:8080"),
    "all://internal.local": httpx.HTTPTransport(),  # no proxy
}

client = httpx.Client(mounts=mounts, timeout=15.0)

Patterns accept a scheme (http://, https:// or all://), an optional host with a leading *. wildcard, and an optional port. A transport created without proxy= connects directly, which is the clean way to exempt a host. Retries and connection limits are set on each transport as well, for example httpx.HTTPTransport(proxy=..., retries=2); the retries value only covers connection failures, not HTTP error codes.

httpx SOCKS5 proxy support

SOCKS is optional in httpx. Install the extra, which pulls in the socksio package, then use a socks5:// URL in the same proxy= argument:

pip install "httpx[socks]"
import httpx

with httpx.Client(proxy="socks5://USER:[email protected]:1080") as client:
    print(client.get("https://proxyv4.com/api/my-ip").json())

Without the extra, the client fails at construction with an ImportError telling you to install httpx[socks]. For ordinary HTTPS scraping, SOCKS5 offers no speed or privacy advantage over an HTTP proxy with CONNECT; pick it when your proxy port only speaks SOCKS5 or when you standardize on one protocol across tools. The trade-offs are covered in HTTP vs SOCKS5.

Using a proxy with httpx AsyncClient

httpx.AsyncClient takes the same proxy= and mounts= arguments. For mounts, use httpx.AsyncHTTPTransport instead of httpx.HTTPTransport; mixing them raises an error the first time a request is routed to the wrong kind.

A common pattern for a crawler with several static IPs is one async client per IP and a simple round-robin over clients. Each client keeps its own connection pool, so you can cap concurrency per IP with httpx.Limits:

import asyncio
import itertools
import httpx

PROXIES = [
    "http://USER:[email protected]:8080",
    "http://USER:[email protected]:8080",
]

async def main(urls):
    limits = httpx.Limits(max_connections=10)
    clients = [httpx.AsyncClient(proxy=p, limits=limits, timeout=20.0) for p in PROXIES]
    pick = itertools.cycle(clients)
    try:
        tasks = [next(pick).get(u) for u in urls]
        for r in await asyncio.gather(*tasks, return_exceptions=True):
            print(r if isinstance(r, Exception) else r.status_code)
    finally:
        await asyncio.gather(*(c.aclose() for c in clients))

asyncio.run(main(["https://proxyv4.com/api/my-ip"] * 4))

Environment variables and trust_env

With the default trust_env=True, a client created without proxy= or mounts= reads HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY (upper or lower case). That makes container deployments easy: set HTTPS_PROXY=http://USER:PASS@IP:PORT and leave the code untouched.

The precedence rule is simple. An explicit proxy= argument replaces the environment entirely, including NO_PROXY, so hosts you expected to bypass will now go through the proxy. Passing trust_env=False turns environment lookups off, which is the safe choice for a test suite that must never inherit a developer's shell settings.

Where a static IPv4 fits an httpx workload

Most httpx jobs that need a proxy are API polling, price monitoring or scraping where a consistent exit IP matters: sessions stay logged in, rate limits are predictable, and a target that keys on IP sees the same address every run. A private IPv4 from ProxyV4 suits that pattern. Each IP has a single tenant for the whole term, the line drops into proxy= after the format change above, and the same port can serve HTTP and SOCKS5 if you enable both on the order page in the dashboard. Switching modes can move the proxy to a new port, so copy the line again afterwards.

Traffic on private IPv4 is unmetered, which matters for crawlers that download large pages. The IP stays the same while the proxy is active, and renewing before expiry keeps the address. Our web scraping proxy guide covers how many IPs a crawl usually needs, and live prices are per IP per month with a single-IP order allowed.

It is the wrong product if you need a new IP on every request, because rotating proxies are not on sale, or if a target only accepts mobile carrier IPs. IPv6 proxies are a separate product that only works on IPv6-ready sites. Buy one IP, run your real httpx job through it, and scale once it behaves.

Reading httpx proxy errors

httpx raises different exception classes depending on where the failure happened. The class tells you whether to look at the network, the credentials or the target.

httpx.ProxyError mentioning 407

On an https:// URL, a rejected login surfaces during the CONNECT step as httpx.ProxyError: 407 Proxy Authentication Required. On a plain http:// URL there is no tunnel, so you get a normal response with status_code == 407 instead of an exception. Either way, recheck the user, password and percent-encoding; the 407 error guide lists the other causes.

ConnectError and ConnectTimeout

httpx.ConnectError with [Errno 111] Connection refused, or a ConnectTimeout, means the client never reached the proxy. The IP or port is wrong, the port changed after a protocol switch, or a firewall on your side blocks outbound traffic. Credentials are not the issue at this stage.

RemoteProtocolError and SSL errors

An ssl error or RemoteProtocolError straight after connecting often means a protocol mismatch: an https:// proxy URL against a plain proxy port, or a socks5:// URL pointed at an HTTP-only port. Match the scheme to what the port actually speaks.

Frequently asked questions

Can I set a different proxy for a single httpx request?

Not directly. httpx configures proxies per client, so create one client per proxy (or use mounts keyed by host) and send each request through the client you want.

Does httpx support socks5h for remote DNS?

The documented scheme is socks5://, available after pip install "httpx[socks]". If remote hostname resolution matters to you, check the httpx changelog for your installed version before relying on another scheme name.

Why does httpx ignore my HTTPS_PROXY variable?

Either the client was created with an explicit proxy= or mounts=, which take precedence, or it was created with trust_env=False. Remove the explicit argument or re-enable trust_env.

Do ProxyV4 proxies work with httpx over both HTTP and SOCKS5?

Yes. Every paid proxy supports HTTP(S), and private IPv4 outside Vietnam and US static ISP proxies also support SOCKS5 with username and password, and you can enable both on the same port from the order page. Use http:// or socks5:// in the URL to match the mode you chose.

Is http2=True compatible with a proxy?

Yes. After pip install "httpx[http2]", an HTTPS request through an HTTP proxy can negotiate HTTP/2 with the target inside the CONNECT tunnel. The proxy only sees the tunnel, not the protocol inside it.

A static IP that drops into Client(proxy=...)

Each ProxyV4 private IPv4 arrives as one `ip:port:user:pass` line that works with httpx over HTTP or SOCKS5, with unmetered traffic and the same address on renewal. Start with one IP and test it in your own client.

Get a static IP

Related articles

Proxy setup
Python requests through an authenticated proxy, step by step
Send Python requests through an authenticated HTTP(S) proxy: build the proxies dict, attach it to a Session, encode odd passwords, rotate a list, check the IP.
Knowledge base
HTTP or SOCKS5: Picking the Proxy Protocol Your Software Needs
HTTP vs SOCKS5 proxy in plain terms: what each protocol carries, why HTTPS works through both, where UDP matters, and how to test which one a server speaks.
Free tools
Check proxies in bulk: status, exit IP and latency
Free online proxy checker: paste up to 100 ip:port:user:pass lines and see which proxies work, their exit IP and latency, plus what each failure result means.
Proxies by platform
Proxies for web scraping: a fixed pool of IPs with unmetered traffic
Web scraping proxies for Python, Scrapy, Playwright and Selenium: a pool of private IPv4 and static ISP addresses, unlimited bandwidth, flat per-IP pricing.
Products
Dedicated datacenter proxies: one private IPv4 per customer
Private IPv4 proxies in the US, Vietnam, Japan, South Korea, Singapore, the UK and Hong Kong. One tenant per IP, HTTP(S) and SOCKS5, no traffic metering.
Proxy setup
Set up your proxy, tool by tool
Proxy setup instructions you can follow with the dashboard open: antidetect browsers, operating systems, browser extensions and scraping libraries, all with authenticated HTTP(S) or SOCKS5.
Knowledge base
Authenticating aiohttp requests against an HTTP or SOCKS5 proxy
aiohttp proxy authentication that survives 3.14: credentials in the URL, proxy_headers with encode_basic_auth, SOCKS5 via aiohttp-socks, per-request proxies.
Knowledge base
Building a Python Proxy Rotation Script with requests
A Python proxy rotation script for requests: thread-safe round robin, sticky sessions per task, dead-proxy removal, timeouts and Retry-After on HTTP 429.
Knowledge base
How to Test a Proxy List in Bulk with Python
Test proxies in bulk with Python: parse ip:port:user:pass, check many at once with timeouts and bounded concurrency, and confirm each exit IP. Two scripts.
Products
Static ISP proxies: residential IPs on consumer networks
Static ISP proxies in the United States and Vietnam: fixed IPs registered to consumer internet providers, rented to one customer, with unmetered traffic.