Python requests proxy: authentication, timeouts and errors
How to route Python requests through an HTTP or SOCKS5 proxy: the proxies dict, username/password auth, environment variables, timeouts, and what ProxyError, 407 and SSLError actually mean.
This guide is for developers who need Python Requests to go through a proxy and keep working when the proxy misbehaves. Examples use placeholder hosts and dummy credentials. Top Proxy does not sell IPs or hand out free lists; we compare the services that do.
The snippets target Requests 2.34.2 on PyPI, which needs Python 3.10 or newer. Proxy behaviour below follows the Requests advanced usage docs. We re-ran the key cases on 2026-10-14 against a pinned loopback fixture (Python 3.14.6, Requests 2.34.2, urllib3 2.8.0, PySocks 1.7.1, TLS verification on). That lab shows protocol behaviour only, not a provider's speed, locations, or IP quality.
01A minimal Python requests proxy example
Every request method takes a proxies dict. Keys are the target URL's scheme; values are the proxy URL:
import requests
proxies = {
"http": "http://203.0.113.10:8080",
"https": "http://203.0.113.10:8080",
}
r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=(3.05, 27))
print(r.status_code, r.json())
Two details trip people up. First, the "https" key usually points at an http:// proxy URL. That is correct: the client asks the proxy for a CONNECT tunnel and TLS runs inside it. Use https:// there only if your provider terminates TLS on the proxy port. Second, write the proxy URL with an explicit scheme (http://, https://, socks5://, or socks5h://) so the protocol is unambiguous. Requests 2.34.2 prepends http:// to a normal schemeless host:port; that is not an invalid proxy URL. InvalidProxyURL is raised when the string still has no host after parsing, not because the scheme was omitted.
httpbin.org/ip returns JSON with an origin field, which is the address the server saw. Compare that with the exit IP or range your provider documents for your plan, and note your direct address on What is my IP. An unchanged address alone does not prove the proxy was bypassed. Some setups exit through the same network you sit in. If you only need to know whether an endpoint answers, use the proxy checker or the longer how to check if a proxy works walkthrough.
A scheme://hostname key routes one exact host differently:
proxies = {
"https": "http://203.0.113.10:8080",
"https://api.internal.example": "http://198.51.100.5:3128",
}
That host match is exact. It does not apply to every name under the same domain.
02Proxy settings on a Session (and the environment trap)
A Session reuses connections and keeps defaults in one place:
session = requests.Session()
session.proxies.update(proxies)
session.get("https://httpbin.org/ip", timeout=10)
The Requests docs warn that session.proxies may not behave as you would expect. Values set there can be overwritten by proxies from the environment (whatever urllib.request.getproxies() returns). An inherited HTTPS_PROXY can silently win. Two ways to make the choice explicit:
# Option 1: pass proxies on every call (the documented fix)
session.get(url, proxies=proxies, timeout=10)
# Option 2: stop the session from reading the environment
session.trust_env = False
session.proxies.update(proxies)
trust_env = False also stops the session reading .netrc and CA bundle variables such as REQUESTS_CA_BUNDLE.
This is not a paper warning. In the 2026-10-14 fixture, Session.proxies pointed at one loopback proxy while HTTP_PROXY / HTTPS_PROXY pointed at another. The environment proxy received the GET. The same session, with proxies= passed on the call, hit the session proxy instead. A second session with trust_env = False used Session.proxies and ignored the environment. If a script "randomly" uses the CI proxy, look here before you rewrite the URL.
03Python requests proxy environment variables
If you do not pass proxies at all, Requests reads the standard variables http_proxy, https_proxy, no_proxy and all_proxy. In a normal process, the uppercase names work too. That is not curl's HTTP rule, where http_proxy is the lowercase variable for HTTP. One CPython exception: if REQUEST_METHOD is set (a CGI process), urllib.request.getproxies_environment() drops the HTTP mapping that came from HTTP_PROXY, so a client Proxy: header cannot inject it. Lowercase http_proxy can still apply.
export HTTP_PROXY="http://203.0.113.10:8080"
export HTTPS_PROXY="http://203.0.113.10:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.example"
python my_script.py
Without NO_PROXY, calls to localhost or internal services can go through the environment proxy and time out. NO_PROXY only governs proxies picked up from the environment. A host matching NO_PROXY can still be proxied if you pass an explicit proxies= dict that covers it.
The fixture confirmed both sides. With NO_PROXY=127.0.0.1,localhost and no proxies= argument, the GET went straight to the local origin; neither lab proxy saw it. The same host, with an explicit proxies= dict, went through the proxy we passed. That is why an "it works in the shell, not in the worker" bug is often two different configuration paths, not two different libraries.
| Where the setting comes from | Applies to | When to use it |
|---|---|---|
proxies= argument on the request | That one call, overriding environment proxies | Scripts that must use a specific exit, e.g. per-request rotation |
Session.proxies | Every call on that session, unless the environment overrides it | Long-running clients, ideally with trust_env = False |
HTTP_PROXY / HTTPS_PROXY / ALL_PROXY | Every Requests call in the process that still trusts the environment | Third-party tools and CI where you cannot edit the code |
NO_PROXY | Hosts that skip environment proxies (explicit proxies= can still cover them) | Localhost, metadata endpoints, internal APIs |
04Python requests proxy authentication (username and password)
Most paid proxies need a login. Requests supports HTTP Basic auth for proxies through the URL itself, http://user:***@host:port, in the proxies dict or in any of the environment variables:
import os
from urllib.parse import quote
user = quote(os.environ["PROXY_USER"], safe="")
password = quote(os.environ["PROXY_PASS"], safe="")
host = "gate.example-provider.com:7000"
proxy_url = f"http://{user}:{password}@{host}"
proxies = {"http": proxy_url, "https": proxy_url}
Load credentials from a secrets manager at runtime. The Requests docs call storing them in environment variables or versioned files a security risk. Percent-encode both the username and the password. Requests unquotes both parts it pulls from the URL, so any @, :, / or # in either has to go through quote(..., safe=""). Otherwise the URL can parse wrong, and the proxy never sees the credentials you meant to send. After decoding, HTTP Basic user-id cannot contain a colon (RFC 7617 section 2); the password can. Percent-encoding a colon in the username does not make that legal: Requests unquotes it back to a colon. An extra unencoded colon in the userinfo is parsed as the start of the password (alice:bob:secret becomes user alice and password bob:secret).
Country or sticky-session flags in the username (user-country-us-session-abc123) are provider syntax, not a Requests feature. They do not grant a geography or an account by themselves.
You may also see requests.auth.HTTPProxyAuth in older answers. It adds a Proxy-Authorization header to the request object. In the loopback test it authenticated plain HTTP requests (200), but the HTTPS request failed with a ProxyError mentioning 407. That fits the header riding on the request rather than on the CONNECT the proxy checks. Prefer credentials in the URL.
Requests handles Basic proxy auth only. NTLM or Kerberos/Negotiate proxies need a third-party auth library or a local helper proxy.
If the question you typed was only "what does 407 mean?", that status has its own page: 407 Proxy Authentication Required. This article stays on how Requests surfaces it.
05SOCKS5 proxies in requests
SOCKS support is an optional extra that pulls in PySocks (1.7.1 on PyPI at the time of writing):
python -m pip install "requests[socks]"
After that, SOCKS URLs work in the same proxies dict, credentials included:
proxies = {
"http": "socks5h://user:***@203.0.113.10:1080",
"https": "socks5h://user:***@203.0.113.10:1080",
}
Pay attention to the h. With socks5://, DNS resolution happens on your machine and only the resulting IP goes to the proxy. With socks5h://, the proxy resolves the hostname. That is the same split curl uses.
The fixture made that visible on https://example.com/. Both schemes returned 200. The SOCKS server logged ATYP 1 (IPv4, 172.66.147.243) for socks5:// and ATYP 3 (hostname example.com) for socks5h://. HTTP calls to 127.0.0.1 do not show the difference, because an IP is already an address. Use socks5h when you do not want your local resolver to see the lookups. For the protocol comparison in catalog language, see SOCKS5 vs HTTP proxies.
| Proxy URL scheme | Extra needed | Who resolves DNS | Typical use |
|---|---|---|---|
http:// | None | Proxy, for the hostname you request | Most paid HTTP(S) gateways |
https:// | None | Proxy | Providers that terminate TLS on the proxy port |
socks5:// | requests[socks] | Your machine | SOCKS proxies where local DNS is acceptable |
socks5h:// | requests[socks] | The proxy | SOCKS proxies, DNS lookups stay on the proxy side |
Unsure what an endpoint speaks? Run it through the proxy checker.
06Python requests proxy timeout
Requests has no default timeout, so a stalled proxy can hang a call for minutes. Always pass timeout, ideally as a (connect, read) tuple:
r = requests.get(url, proxies=proxies, timeout=(3.05, 27))
The connect value covers the TCP connection, which with a proxy means the connection to the proxy. The docs suggest a value slightly above a multiple of 3 to line up with TCP retransmission. The read value is the maximum gap between bytes from the server, not a cap on total download time. Latency depends on the provider, exit and target, so set the read value from response times measured on your actual endpoint.
A useful catch: when the proxy itself does not accept the TCP connection in time, Requests 2.34.2 raised ProxyError wrapping urllib3's ConnectTimeoutError, not a top-level ConnectTimeout. In the fixture, timeout=(1.0, 5) against 192.0.2.1:8080 produced that wrapper. After a working proxy had connected, a slow origin with timeout=(3.05, 1.0) raised ReadTimeout. Catch ProxyError and ReadTimeout before a generic ConnectionError, and inspect the message or __cause__ if you need to tell "proxy never answered" from "proxy answered, then the site went quiet".
For transient failures, mount an adapter with bounded retries rather than writing a loop by hand:
from requests.adapters import HTTPAdapter
from urllib3.util import Retry
retry = Retry(total=3, backoff_factor=0.5, status_forcelist=[429, 502, 503, 504])
session.mount("https://", HTTPAdapter(max_retries=retry))
session.mount("http://", HTTPAdapter(max_retries=retry))
Status retries follow allowed_methods. urllib3 2.8.0's default set is GET, HEAD, PUT, DELETE, OPTIONS and TRACE; POST is excluded unless you add it. Enable replay only for operations that are safe to send twice. total=3 caps retry attempts, not wall-clock time. When the response has Retry-After, urllib3 waits for that delay if respect_retry_after_header is true (the default).
Retries will not fix a 407, a bad CA, or trust_env pointing at the wrong gateway. They only help when the failure is actually transient.
07Python requests proxy errors: what each exception means
Order your except blocks carefully. ProxyError, SSLError and ConnectTimeout all subclass ConnectionError, and ConnectTimeout is also a Timeout. Catch the specific ones first:
from requests.exceptions import (
ProxyError, SSLError, ConnectTimeout, ReadTimeout,
ConnectionError, InvalidProxyURL, RequestException,
)
try:
r = session.get(url, proxies=proxies, timeout=(3.05, 27))
r.raise_for_status()
except ProxyError as e:
... # proxy unreachable, CONNECT refused, or connect-timeout to the proxy; check the message for 407
except SSLError as e:
... # certificate problem; fix trust, don't disable verification
except ConnectTimeout:
... # could not connect in time (more often seen without a proxy)
except ReadTimeout:
... # connected, but the server went quiet
except InvalidProxyURL:
... # malformed proxy URL
except ConnectionError:
... # DNS failure, reset, other network errors
except RequestException:
... # anything else from requests
| Symptom | Likely cause | What to try |
|---|---|---|
ProxyError with no 407 in the message | Nothing accepting connections at that host/port, proxy down, a network/allowlist block, or a connect timeout to the proxy | Check host and port, then test the endpoint in the proxy checker; credentials are not the first suspect |
ProxyError mentioning 407 on an HTTPS URL | The CONNECT carried no credentials the proxy accepted: none sent, set only via HTTPProxyAuth, mis-encoded, wrong format, or plan inactive | Put encoded credentials in the proxy URL; confirm the username format and plan status |
| Response with status 407 on an HTTP URL | The proxy is asking for credentials; on a request sent without them this is just the challenge | Add credentials to the proxy URL; if they were already there, check encoding and format |
| Response with status 401 | The destination, not the proxy, wants authentication | Fix the site's own auth; the proxy part worked |
Requests ignores your Session.proxies | Environment proxies override them | Pass proxies= per call or set trust_env = False |
InvalidSchema: Missing dependencies for SOCKS support | requests[socks] not installed | python -m pip install "requests[socks]" |
SSLError: CERTIFICATE_VERIFY_FAILED | Intercepting proxy or a lab/self-signed certificate the default bundle does not trust | Point verify= or REQUESTS_CA_BUNDLE at that proxy's CA file |
| Hangs indefinitely | No timeout set | Always pass a (connect, read) tuple |
origin doesn't match the exit you expected | Proxy not applied for that scheme, NO_PROXY matched while relying on environment proxies, or a different route than you assumed | Set both http and https keys; if using env proxies, check NO_PROXY; compare with the provider's documented exit IP/range |
What a local test showed

We ran these patterns against a loopback test proxy on 2026-10-14: Python 3.14.6, Requests 2.34.2, urllib3 2.8.0, certifi 2026.07.22, PySocks 1.7.1, timeout=(3.05, 10) unless noted, TLS verification on. Dummy user demo; the password contained punctuation and was percent-encoded in URLs, then redacted in logs. HTTPS checks used https://example.com/ plus a local server with a lab CA. The rows below are captured observations from that fixture, not a count of passing automated tests. This shows protocol behaviour only.
| Case | HTTP target | HTTPS target |
|---|---|---|
| No proxy credentials | 407 response | ProxyError mentioning 407 |
| Percent-encoded credentials in proxy URL | 200 | 200 (example.com and lab TLS with verify= set to the lab CA) |
HTTPProxyAuth only | 200 | ProxyError mentioning 407 |
| Proxy port closed | ProxyError, no 407 | not tested |
| Valid proxy auth, site returns 401 | 401 response from the site | not tested |
| Default CA vs lab self-signed cert | n/a | SSLError: CERTIFICATE_VERIFY_FAILED; 200 after trusting the lab CA |
Session.proxies vs HTTP_PROXY | Environment proxy received the GET | not tested |
proxies= on the call, env set | Session/open proxy received the GET | not tested |
trust_env = False | Session.proxies used; env ignored | not tested |
NO_PROXY matches the host | Direct to origin; no proxy hit | not tested |
Explicit proxies= on a NO_PROXY host | Still proxied | not tested |
| Connect timeout to the proxy | ProxyError wrapping ConnectTimeoutError | not tested |
| Read timeout through a working proxy | ReadTimeout | not tested |
SOCKS5 with encoded credentials returned 200 for HTTP and for https://example.com/. DNS split: socks5:// delivered an IPv4 address to the proxy; socks5h:// delivered the hostname.
Certificates, intercepting proxies and verify
A corporate TLS-inspection gateway or a local intercepting proxy re-signs HTTPS with its own certificate authority, which Requests rejects. Trust that CA explicitly instead of switching verification off:
r = requests.get(
url,
proxies={"https": "http://127.0.0.1:8080"},
verify="/path/to/proxy-ca.pem",
timeout=10,
)
or export REQUESTS_CA_BUNDLE=/path/to/ca.pem for the whole process. Convert a DER export to PEM first. The lab self-signed origin reproduced the same class of failure: default verify=True raised SSLError (certificate verify failed: self-signed certificate); the same request with verify= pointing at the lab CA returned 200. verify=False makes Requests accept any certificate and ignore hostname mismatches, which defeats TLS for everything that client sends. It is not a normal fix for a proxy that "does not work".
08Rotating proxies in Python
Many commercial providers rotate for you behind a single gateway host. Depending on the tariff, the exit may change per request or on a session interval, and a session ID in the username usually pins one exit for a while rather than giving every call a new one. Those rules are provider settings, so check their docs. Sticky vs rotating proxies covers the product language. If you manage a list of endpoints yourself, pick one per request and pass it via proxies=:
import itertools
pool = itertools.cycle(
[
"http://user:***@203.0.113.10:8080",
"http://user:***@203.0.113.11:8080",
]
)
for url in urls:
p = next(pool)
session.get(url, proxies={"http": p, "https": p}, timeout=(3.05, 27))
Pass the proxy per call, since environment proxies can override Session.proxies. The exit type is a separate choice: datacenter, residential or mobile. Price and how a target site treats the traffic depend on the tariff, the target and the IP's reputation, not on the type label alone. A proxy does not confer geography or account eligibility by itself.
Before you buy, confirm that the plan you pick supports the protocol (HTTP or SOCKS5) and auth method (login or IP allowlist) your code needs. Browser automation is a different stack; for Playwright contexts see Playwright proxy. Providers in our catalog with proxy gateways:

Bright Data is a large proxy network for data collection: residential, mobile, ISP and datacenter IPs in about 195 countries. Residential traffic can be paid as you go with no subscription, and datacenter and ISP addresses come in packs from 10 IPs. Residential and mobile access requires identity verification.

Oxylabs sells residential, mobile, ISP and datacenter proxies under one monthly subscription from $30. Buyer payments: cards, wire transfer, AliPay, PayPal.

SOAX sells rotating residential and mobile proxies on a shared credit pool, with datacenter and ISP in the same plans. Builder starts at $200/mo + VAT (200 credits); Tier 1 traffic is $3/GB on Builder.

Decodo (formerly Smartproxy) sells residential and datacenter proxies. Residential: $4/GB without a monthly plan, or monthly packs from $3.75/GB for 3 GB. Payments: cards, PayPal, Alipay, Google/Apple Pay, crypto (with limits).
How do I use a proxy with Python requests?
How do I add a username and password to a requests proxy?
Why does Python requests return 407 Proxy Authentication Required?
Does requests support SOCKS5 proxies?
Does requests use the HTTP_PROXY environment variable?
What timeout should I set for requests through a proxy?
Should I set verify=False if the proxy breaks HTTPS?
Related articles
Proxy not working? A diagnostic checklist for connection failed and refused errors
Proxy connection failed, refused or timing out? Test your network without the proxy, then host and port, protocol, login and allowlist, the target site and your app's route.
How mobile proxies work: IP rotation and sessions
Why a site still remembers you after an IP change: what a mobile exit is made of, why carriers use CGN, the three kinds of "session", what rotation really changes, and what to check before renting.
Proxy bandwidth and pricing: estimate cost per successful request
What proxy bandwidth means on a bill, what uses up traffic, how retries change the real cost per successful request, and how to find the break-even between plans.



