How to Use Proxies With Python HTTPX
Configure HTTP, HTTPS, SOCKS5, authenticated, environment and route-specific proxies in Python HTTPX, with fixes for common failures.

Direct answer: Configure one proxy with httpx.Client(proxy="http://proxy-host:port") or pass proxy= to a top-level request. For different proxies by scheme, domain or port, use mounts with httpx.HTTPTransport(proxy=...). HTTPX reads HTTP_PROXY, HTTPS_PROXY and ALL_PROXY from the environment unless you set trust_env=False. SOCKS support requires the optional httpx[socks] extra.
Install HTTPX
HTTPX requires Python 3.9 or newer. Install the base package for HTTP and HTTPS proxies:
python -m pip install httpx
Install the SOCKS extra when your endpoint starts with socks5:// or socks5h://:
python -m pip install "httpx[socks]"
Keep proxy credentials out of source control, shell history and request logs. Prefer environment variables or a secrets manager, and URL-encode reserved characters in usernames and passwords.
Use one proxy for all requests
A client is the usual choice for a script or service because it reuses connections. The proxy URL can include credentials.
import httpx
proxy = "http://proxy-host:port"
# Example with credentials:
# proxy = "http://username:password@proxy-host:port"
with httpx.Client(proxy=proxy, timeout=30.0) as client:
response = client.get("https://example.com")
response.raise_for_status()
print(response.status_code)
print(response.text[:200])
For a single request, pass proxy directly:
import httpx
response = httpx.get(
"https://example.com",
proxy="http://proxy-host:port",
timeout=30.0,
)
response.raise_for_status()
HTTPX supports both synchronous and asynchronous APIs. Use one long-lived client per process or service instead of creating a new client for every URL.
Route HTTP and HTTPS through different proxies
HTTPX uses transport mounts for route-specific behavior. The keys are URL patterns, and the transport supplies the proxy.

import httpx
proxy_mounts = {
"http://": httpx.HTTPTransport(proxy="http://localhost:8030"),
"https://": httpx.HTTPTransport(proxy="http://localhost:8031"),
}
with httpx.Client(mounts=proxy_mounts, timeout=30.0) as client:
http_response = client.get("http://example.com")
https_response = client.get("https://example.com")
print(http_response.status_code, https_response.status_code)
The HTTPS destination gotcha is easy to miss: for an https:// route, the proxy URL commonly uses the http:// scheme. An HTTP proxy can create a TCP tunnel with CONNECT, after which HTTPX performs TLS with the destination. The proxy scheme describes the connection to the proxy; it does not necessarily describe the destination scheme. See the HTTPX proxies guide.
Match domains, ports and no-proxy exceptions
Mount matching is more specific before less specific. You can route one host through a special proxy while retaining a default route, or bypass a matching route with None.
import httpx
mounts = {
"https://internal.example.com": None,
"https://api.example.com:8443": httpx.HTTPTransport(
proxy="http://regional-proxy:8080"
),
"https://": httpx.HTTPTransport(proxy="http://default-proxy:8080"),
}
with httpx.Client(mounts=mounts, timeout=30.0) as client:
public = client.get("https://www.example.com")
internal = client.get("https://internal.example.com")
regional = client.get("https://api.example.com:8443/data")
Use a trailing slash or a complete scheme pattern when defining mounts, and test the exact host and port patterns your application generates. This model differs from Requests’ proxies={"http": ..., "https": ...} mapping: HTTPX mounts are transport routes and can express more specific patterns.
Use environment proxy variables
HTTPX honors HTTP_PROXY, HTTPS_PROXY and ALL_PROXY by default. NO_PROXY lists hosts or URLs that should bypass those settings. This is useful in containers and CI, but ambient variables can also cause surprising routing.
export HTTP_PROXY=http://proxy.example:8080
export HTTPS_PROXY=http://proxy.example:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com
import httpx
# Ignore proxy and certificate-related environment settings.
with httpx.Client(trust_env=False, timeout=30.0) as client:
response = client.get("https://example.com")
response.raise_for_status()
You can also set trust_env=False on a top-level call. Read the HTTPX environment variables documentation when diagnosing behavior that differs between your laptop and deployment environment.
Configure SOCKS5
After installing httpx[socks], configure a SOCKS endpoint with the same proxy parameter:
import httpx
proxy = "socks5://user:password@127.0.0.1:1080"
with httpx.Client(proxy=proxy, timeout=30.0) as client:
response = client.get("https://example.com")
response.raise_for_status()
print(response.url)
The optional extra installs socksio; a base HTTPX installation does not guarantee SOCKS functionality. If DNS handling at the proxy is required by your setup, check the SOCKS scheme supported by your installed HTTPX version and proxy server, then verify it with a host whose DNS result you can observe.
Authentication and URL construction
Credentials are represented as URL user information:
proxy = "http://username:password@localhost:8030"
Special characters must be percent-encoded. For example, a password containing @ should use %40. Build URLs with a URL library or encode each user-information component rather than concatenating untrusted strings. Never print the full proxy URL in logs; redact the password and, when appropriate, the username and host.
Async HTTPX with a proxy
AsyncClient supports the same proxy and mount configuration. Share one client between tasks to retain connection pooling, and close it with an async context manager.
import asyncio
import httpx
async def fetch(url: str) -> tuple[str, int]:
async with httpx.AsyncClient(
proxy="http://proxy.example:8080",
timeout=httpx.Timeout(30.0, connect=10.0),
) as client:
response = await client.get(url)
response.raise_for_status()
return url, response.status_code
async def main() -> None:
print(await fetch("https://example.com"))
asyncio.run(main())
For many URLs, create the AsyncClient once in main(), use a semaphore to limit concurrency, and close it after all tasks finish. Unbounded concurrency can exhaust file descriptors, proxy connection limits or the destination’s rate limits.
Timeouts, retries and reliability
Set explicit timeouts. HTTPX lets you separate connect, read, write and pool timeouts:
import httpx
timeout = httpx.Timeout(30.0, connect=10.0, pool=5.0)
with httpx.Client(proxy="http://proxy.example:8080", timeout=timeout) as client:
response = client.get("https://example.com")
HTTPX does not automatically retry every failed request. Add retries at the application or transport layer only for operations that are safe to repeat, such as idempotent GET requests. Use bounded exponential backoff and distinguish proxy connection failures, read timeouts, HTTP 407 authentication responses and destination 4xx/5xx responses. A retry cannot fix invalid credentials or a proxy that cannot reach the destination.
Equivalent cURL and Node.js examples
These examples help compare a working proxy outside Python.
curl --proxy http://proxy-host:port https://example.com
curl --proxy http://username:password@proxy-host:port https://example.com
curl --socks5-hostname user:password@127.0.0.1:1080 https://example.com
const proxyUrl = 'http://proxy-host:port';
// Node's built-in fetch does not accept a proxy URL directly.
// Use an HTTP(S) agent from your chosen proxy-agent package.
// const agent = new HttpProxyAgent(proxyUrl);
// const response = await fetch('https://example.com', { dispatcher: agent });
Node’s proxy-agent APIs vary by package and version, so consult the package documentation for the dispatcher or agent option used by your runtime.
Common errors and fixes
| Error or symptom | Likely cause | Fix |
|---|---|---|
ConnectError or connection refused |
Wrong host/port, stopped proxy, firewall or unreachable network | Check the endpoint with cURL from the same machine and verify the proxy listener and egress rules. |
| HTTP 407 Proxy Authentication Required | Missing, incorrect or incorrectly encoded credentials | Use URL userinfo, percent-encode reserved characters, and confirm the account is allowed to use that proxy. |
| HTTPS request fails while HTTP works | Proxy URL for the HTTPS route uses the wrong scheme or the proxy cannot tunnel CONNECT | Try an http:// proxy URL for the https:// mount and confirm CONNECT support. |
| TLS certificate or verify error | Intercepting proxy certificate is untrusted, or environment certificate settings differ | Install the proxy CA through your platform’s trust store when appropriate. Use trust_env=False to isolate environment effects; do not disable verification as a routine fix. |
| SOCKS scheme is unsupported | socksio is not installed |
Install python -m pip install "httpx[socks]" and restart the process. |
| Requests unexpectedly use a proxy | HTTPX read ambient proxy variables | Inspect HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY, or set trust_env=False. |
Proxy URL itself uses https:// and fails |
HTTPX documents incomplete HTTPS-proxy support | Use the current HTTPX troubleshooting guide. In many deployments an HTTP proxy URL is the compatible choice for an HTTPS destination. |
| Slow requests or pool timeouts | New clients per request, too much concurrency or overloaded proxy | Reuse a client, set pool limits, cap concurrency and measure connect versus read time. |

Performance and cost considerations
- Reuse connections: A long-lived client enables pooling and avoids repeated TCP and TLS setup.
- Choose concurrency deliberately: Match task count to proxy capacity, destination limits and your file-descriptor budget.
- Measure the route: Log redacted proxy identity, status, elapsed time and exception type. Avoid logging credentials or sensitive response bodies.
- Cache safe responses: Application-level caching can reduce proxy traffic for idempotent requests, but respect destination cache headers and freshness requirements.
- Proxy pricing: HTTPX itself does not provide proxy service or proxy pricing. Your proxy provider may charge by bandwidth, requests, ports or time; confirm its terms directly.
Or skip the browser setup
If your goal is a clean image or PDF of a web page rather than making HTTP requests through a proxy, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
See the ScreenshotNeo documentation for all options. Before capture, it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. ScreenshotNeo also supports full-page and element captures, lazy-image loading, dark mode, device presets, custom viewport and retina scale, PDF controls, custom CSS and JavaScript, clicks, waits, blocking rules, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs, webhooks, bulk capture and a usage API. An MCP server provides take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
Should I use a client or a top-level request?
Use a client for multiple requests, connection reuse, shared configuration and explicit cleanup. Use a top-level call for a one-off operation.
Is an HTTPS proxy required for an HTTPS website?
No. HTTPX’s proxy guide says an HTTP proxy URL is commonly correct for an HTTPS route because the proxy tunnels the connection. An HTTPS proxy endpoint is a separate capability and has documented support concerns.
Does NO_PROXY override explicit mounts?
NO_PROXY controls environment-based proxying. Explicit client mounts are clearer when you need deterministic per-host behavior; test the final route configuration rather than relying on assumptions.
Can a proxy guarantee anonymity?
No. A proxy changes network routing. It does not by itself guarantee anonymity, privacy, authentication security or access to a blocked service.
How do I confirm which proxy HTTPX used?
Inspect environment variables and explicit mounts, then reproduce the request with cURL from the same host. Record only redacted configuration and timing data in application logs.


