Routing Python httpx traffic through an authenticated proxy
By the ProxyV4 Engineering Team · 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.
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 inhttpx.HTTPTransport(proxy=url)(orhttpx.AsyncHTTPTransportfor async clients). - Per-request proxies: httpx never supported a
proxy=keyword onclient.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