httpx proxy: unexpected keyword argument 'proxies' fix (tested)

TypeError: Client.__init__() got an unexpected keyword argument 'proxies': httpx 0.28 takes proxy="http://host:port" (one URL) instead. For per-scheme proxies use mounts={"http://": httpx.HTTPTransport(proxy=...)}.

Measured with httpx 0.28.1 on Python 3.13.5. The "proxy" is a local http.server that echoes the request line it receives: when a request goes through it, the path is the full target URL (http://example.invalid/...), which proves the proxy was used. example.invalid does not resolve, so a request that skips the proxy fails.

1. proxies= is a TypeError: use proxy=

import httpx
from srv import start
proxy = start()   # local server that echoes the request line it receives

try:
    httpx.Client(proxies=proxy)
except TypeError as e:
    print("TypeError:", e)

with httpx.Client(proxy=proxy) as client:
    print(client.get("http://example.invalid/hello").json())

Output:

TypeError: Client.__init__() got an unexpected keyword argument 'proxies'
{'method': 'GET', 'path': 'http://example.invalid/hello', 'auth': None}

httpx 0.28.1 rejects the old proxies= argument (found in many tutorials and in code written for older httpx). Pass a single URL with proxy=, on httpx.Client, httpx.AsyncClient or a one-off httpx.get(..., proxy=...). Credentials go in the URL: http://user:pass@proxy:3128.

2. Different proxies per scheme or host: mounts=

import httpx
from srv import start
proxy = start()

mounts = {"http://": httpx.HTTPTransport(proxy=proxy)}   # proxy only plain-http traffic
with httpx.Client(mounts=mounts) as client:
    print(client.get("http://example.invalid/mounted").json()["path"])

Output:

http://example.invalid/mounted

The old proxies={"http://": ..., "https://": ...} dict becomes mounts= with one httpx.HTTPTransport(proxy=...) (or AsyncHTTPTransport for AsyncClient) per URL pattern. Requests that match no mount use a direct connection.

3. HTTP_PROXY / HTTPS_PROXY / NO_PROXY environment variables

import os, subprocess, sys
from srv import start
proxy = start()

code = "import httpx; print(httpx.get('http://example.invalid/env').json()['path'])"
for extra in ({"HTTP_PROXY": proxy}, {"HTTP_PROXY": proxy, "NO_PROXY": "example.invalid"}):
    env = {k: v for k, v in os.environ.items() if "PROXY" not in k.upper()} | extra
    out = subprocess.run([sys.executable, "-c", code], env=env, capture_output=True, text=True)
    print(sorted(extra), "->", out.stdout.strip() or out.stderr.strip().splitlines()[-1])

Output:

['HTTP_PROXY'] -> http://example.invalid/env
['HTTP_PROXY', 'NO_PROXY'] -> httpx.ConnectError: [Errno -2] Name or service not known

With the default trust_env=True, httpx picks up HTTP_PROXY, HTTPS_PROXY and ALL_PROXY, and NO_PROXY excludes hosts (here the request went direct and failed on DNS). If an explicit proxy= seems ignored or a proxy is used unexpectedly, check these variables, or pass trust_env=False.

4. SOCKS proxies need an extra

import httpx
try:
    httpx.Client(proxy="socks5://127.0.0.1:1080")
except ImportError as e:
    print("ImportError:", e)

Output:

ImportError: Using SOCKS proxy, but the 'socksio' package is not installed. Make sure to install httpx using `pip install httpx[socks]`.

Install pip install "httpx[socks]" to use socks5:// proxy URLs.

Related: httpx vs requests, httpx CERTIFICATE_VERIFY_FAILED (common behind a TLS-inspecting corporate proxy), httpx timeout.

Written with AI assistance. Measured on 2026-10-23 with httpx 0.28.1 on Python 3.13.5, using a local http.server as an echoing HTTP proxy. Each block was run verbatim and the output pasted unedited. PlainHeaders is our extension; httpx is free.