Python requests proxy: authentication, timeouts and errors

15 min read

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 fromApplies toWhen to use it
proxies= argument on the requestThat one call, overriding environment proxiesScripts that must use a specific exit, e.g. per-request rotation
Session.proxiesEvery call on that session, unless the environment overrides itLong-running clients, ideally with trust_env = False
HTTP_PROXY / HTTPS_PROXY / ALL_PROXYEvery Requests call in the process that still trusts the environmentThird-party tools and CI where you cannot edit the code
NO_PROXYHosts 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 schemeExtra neededWho resolves DNSTypical use
http://NoneProxy, for the hostname you requestMost paid HTTP(S) gateways
https://NoneProxyProviders that terminate TLS on the proxy port
socks5://requests[socks]Your machineSOCKS proxies where local DNS is acceptable
socks5h://requests[socks]The proxySOCKS 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
SymptomLikely causeWhat to try
ProxyError with no 407 in the messageNothing accepting connections at that host/port, proxy down, a network/allowlist block, or a connect timeout to the proxyCheck host and port, then test the endpoint in the proxy checker; credentials are not the first suspect
ProxyError mentioning 407 on an HTTPS URLThe CONNECT carried no credentials the proxy accepted: none sent, set only via HTTPProxyAuth, mis-encoded, wrong format, or plan inactivePut encoded credentials in the proxy URL; confirm the username format and plan status
Response with status 407 on an HTTP URLThe proxy is asking for credentials; on a request sent without them this is just the challengeAdd credentials to the proxy URL; if they were already there, check encoding and format
Response with status 401The destination, not the proxy, wants authenticationFix the site's own auth; the proxy part worked
Requests ignores your Session.proxiesEnvironment proxies override themPass proxies= per call or set trust_env = False
InvalidSchema: Missing dependencies for SOCKS supportrequests[socks] not installedpython -m pip install "requests[socks]"
SSLError: CERTIFICATE_VERIFY_FAILEDIntercepting proxy or a lab/self-signed certificate the default bundle does not trustPoint verify= or REQUESTS_CA_BUNDLE at that proxy's CA file
Hangs indefinitelyNo timeout setAlways pass a (connect, read) tuple
origin doesn't match the exit you expectedProxy not applied for that scheme, NO_PROXY matched while relying on environment proxies, or a different route than you assumedSet 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

Observed Requests test results from the controlled local proxy fixture

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.

CaseHTTP targetHTTPS target
No proxy credentials407 responseProxyError mentioning 407
Percent-encoded credentials in proxy URL200200 (example.com and lab TLS with verify= set to the lab CA)
HTTPProxyAuth only200ProxyError mentioning 407
Proxy port closedProxyError, no 407not tested
Valid proxy auth, site returns 401401 response from the sitenot tested
Default CA vs lab self-signed certn/aSSLError: CERTIFICATE_VERIFY_FAILED; 200 after trusting the lab CA
Session.proxies vs HTTP_PROXYEnvironment proxy received the GETnot tested
proxies= on the call, env setSession/open proxy received the GETnot tested
trust_env = FalseSession.proxies used; env ignorednot tested
NO_PROXY matches the hostDirect to origin; no proxy hitnot tested
Explicit proxies= on a NO_PROXY hostStill proxiednot tested
Connect timeout to the proxyProxyError wrapping ConnectTimeoutErrornot tested
Read timeout through a working proxyReadTimeoutnot 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 — residential and datacenter proxies
Bright Data — residential and datacenter proxies4.41452

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.

10 countries
$5.00
per 1 GB
Oxylabs — residential and datacenter proxies
Oxylabs — residential and datacenter proxies3.9779

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

10 countries
$0.45
per 1 GB
SOAX — residential and mobile proxies
SOAX — residential and mobile proxies3.8218

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.

85 countries
$3.00
per 1 GB
Visit site
Decodo (Smartproxy) — residential and datacenter proxies
Decodo (Smartproxy) — residential and datacenter proxies4.22603

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).

83 countries
$0.38
per 1 GB

How do I use a proxy with Python requests?

Pass a dict like {"http": "http://host:port", "https": "http://host:port"} as the proxies argument. Keys are the target URL's scheme; values are proxy URLs. Prefer an explicit scheme on those values so HTTP and SOCKS are not mixed up. A normal host:port with no scheme is prepended with http:// in Requests 2.34.2; it is not rejected as InvalidProxyURL.

How do I add a username and password to a requests proxy?

Put them in the proxy URL (http://user:***@host:port), percent-encoding both parts with urllib.parse.quote(value, safe=""), and load them from a secrets manager rather than hardcoding them. After decoding, HTTP Basic user-id cannot contain a colon (RFC 7617); the password can. Do not rely on a percent-encoded colon to put a colon in the username.

Why does Python requests return 407 Proxy Authentication Required?

The proxy wants credentials it did not get or did not accept. On a request sent without credentials, a 407 is just the challenge. Otherwise check encoding, username format and plan status. HTTPS targets raise a ProxyError mentioning 407; HTTP targets return a 407 response. A ProxyError without 407, such as from a closed port, points to connectivity instead. HTTPProxyAuth authenticated HTTP in our lab but not HTTPS CONNECT.

Does requests support SOCKS5 proxies?

Yes, after python -m pip install "requests[socks]". Use socks5h:// to let the proxy resolve hostnames, or socks5:// to resolve them locally. In the lab, socks5 delivered an IPv4 address for example.com and socks5h delivered the hostname.

Does requests use the HTTP_PROXY environment variable?

Yes, when you do not pass proxies: it reads http_proxy, https_proxy, all_proxy and no_proxy. In a normal process the uppercase names work too. If REQUEST_METHOD is set (CGI), urllib ignores HTTP_PROXY for HTTP so a Proxy header cannot inject it; lowercase http_proxy can still apply. That is not curl's lowercase-only HTTP rule. Environment proxies can override Session.proxies, so pass proxies per call or set session.trust_env = False. NO_PROXY only skips environment proxies; an explicit proxies= dict can still cover those hosts.

What timeout should I set for requests through a proxy?

Always set one; Requests has no default. Start with a tuple like (3.05, 27) and adjust after measuring response times through your actual proxy endpoint. A connect timeout to the proxy may surface as ProxyError wrapping ConnectTimeoutError; a quiet origin after connect is ReadTimeout.

Should I set verify=False if the proxy breaks HTTPS?

No. Trust the intercepting proxy's CA with verify= or REQUESTS_CA_BUNDLE. verify=False accepts any certificate and ignores hostname mismatches. In the lab, a self-signed origin failed default verification and succeeded only after the lab CA was passed to verify=.