Home/Blog/Python Requests Proxy

Proxy with Python Requests: SOCKS5, Auth, and the Errors That Actually Bite

P
ProxyBase Team
November 2026 • 9 min read

Adding a proxy to Python requests looks like a two-line change until authentication, DNS, or connection pooling gets involved. Then the same two lines fail in ways the status code does not explain.

Getting it right means handling the SOCKS extra, the DNS choice between socks5 and socks5h, and authenticated sessions, then knowing which failures come from the proxy.

Install the SOCKS extra first

Plain requests does not speak SOCKS. The support lives in an optional extra that installs PySocks:

pip install requests[socks]

If the code later fails with InvalidSchema and a message about missing SOCKS dependencies, this is the missing piece. Pin the extra in your lockfile as well. A fresh environment that installs plain requests will reproduce the same failure.

Build the proxy dictionary

A SOCKS5 proxy goes in a dictionary. Both keys point at the same URL:

import requests proxy = "socks5h://username:password@api.proxybase.xyz:1082" proxies = {"http": proxy, "https": proxy} r = requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=30) print(r.text)

The key is the scheme of the request being made. The proxy protocol comes from the value. An https:// target looks up the https key and then parses the socks5h:// URL inside it.

Pick socks5h to keep DNS at the exit

socks5:// resolves the target hostname on your machine before the connection reaches the proxy. Your resolver sees every hostname, and the exit only receives an IP address. That is a DNS leak, and it can also break geo-targeting when the target uses DNS-based routing or when your resolver returns a CDN edge for the wrong region.

socks5h:// sends the hostname to the proxy and resolves it from the exit network. Use this for scraping, geo-restricted sites, and anything where the exit should decide what the name resolves to. The h is the difference between changing your IP and changing your apparent location end to end.

Use socks5h unless you have a specific reason to resolve locally.

Put credentials in the proxy URL

When the proxy requires a username and password, put them in the URL. PySocks reads them during the SOCKS handshake. requests.auth.HTTPProxyAuth is for HTTP proxy 407 responses and does nothing for SOCKS.

Credentials with reserved characters must be URL-encoded. An unescaped @ in a password is the classic failure: the parser treats the text after it as the host, and you get InvalidURL or a connection to the wrong place.

import os from urllib.parse import quote user = quote(os.environ["PROXY_USER"], safe="") password = quote(os.environ["PROXY_PASS"], safe="") proxy = f"socks5h://{user}:{password}@api.proxybase.xyz:1082" proxies = {"http": proxy, "https": proxy}

Keep the credentials in environment variables or a secret manager. A session token pasted into a notebook cell or a committed script is a leaked token.

Session reuse changes how rotation behaves

A top-level requests.get creates a new Session for each call, then closes it. Every call opens a new connection. On a rotating SOCKS session, that means a new exit per call.

A requests.Session pools connections. Keep-alive reuses the TCP connection, and a rotating session chooses its seller per connection. A Session can therefore pin one exit for a whole batch. The pool is behaving as designed; the rotation policy applies per connection.

If you need cookies and rotation at the same time, keep the Session for cookie state but force a new connection per request:

session = requests.Session() session.headers.update({"Connection": "close"})

On a sticky session, pooling is fine. The seller is fixed when the session is created, so a reused connection and a new connection reach the same exit until you rotate. The rotation guide covers per-connection versus per-request behavior in detail.

Open a ProxyBase session from Python

With the v2 marketplace, you open a session and the gateway accepts the session id and token. The token comes from the challenge and verify flow and starts with sk_.

import requests API = "https://api.proxybase.xyz/v2" TOKEN = "sk_your_session_token" r = requests.post( f"{API}/sessions", headers={"Authorization": f"Bearer {TOKEN}"}, json={ "country": "US", "network_type": "residential", # or "mobile" "session_type": "sticky", # or "rotating" "spend_cap_microcredits": 5_000_000, }, timeout=15, ) r.raise_for_status() session_id = r.json()["session_id"] proxy = f"socks5h://{session_id}:{TOKEN}@api.proxybase.xyz:1082" proxies = {"http": proxy, "https": proxy} response = requests.get( "https://api.ipify.org?format=json", proxies=proxies, timeout=(5, 30), ) print(response.json())

Country and network type are body fields. Neither appears in the credential string. The username is the session id, the password is the session token, and the v2 gateway listens on port 1082.

Set spend_cap_microcredits before the job. Retries and failed requests consume bandwidth. The cap is the difference between a bad batch and a bad invoice.

Timeouts and retries that do not waste bandwidth

Use a timeout tuple. requests treats a single number as both the connect and read timeout. A proxy that accepts the connection and then stalls mid-response is a read timeout, and without one your worker hangs.

Set retries on the adapter, not in a bare loop. Retry 429 and 5xx responses. Do not retry 401, 403, or a SOCKS authentication failure. Every retry consumes billed bandwidth, so cap the total. If a request fails twice on two different exits, the problem is probably not the IP.

from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry retry = Retry( total=2, backoff_factor=0.5, status_forcelist=[429, 500, 502, 503, 504], allowed_methods=["GET", "HEAD"], ) session = requests.Session() session.mount("http://", HTTPAdapter(max_retries=retry)) session.mount("https://", HTTPAdapter(max_retries=retry))

The errors you will actually hit

SymptomCauseFix
InvalidSchema: Missing dependencies for SOCKS supportPlain requests has no SOCKS supportpip install requests[socks]
ProxyError: Unable to connect to proxyWrong host or port, gateway unreachable, or the session is not activeCheck api.proxybase.xyz:1082 and confirm the session
ProxyError: SOCKS5 authentication failedBad session id or token, or unescaped credentialsSession id as username, token as password, URL-encode both
InvalidURL, or the host looks truncatedAn unescaped @, :, or / in the credentialsurllib.parse.quote(value, safe="")
407 Proxy Authentication RequiredYou are pointing at an HTTP proxy, not a SOCKS proxyUse socks5h://; SOCKS auth does not return 407
ConnectionError or RemoteDisconnectedThe seller or connection dropped mid-requestRetry on a new connection; rotate a sticky session
SSLErrorTarget TLS handshake, certificate, or interceptionNot a SOCKS auth error. Inspect the target certificate chain
The request succeeds from your origin IPThe proxy is not in the path, or environment proxies interfereLog the exit IP and set session.trust_env = False
Rotation stops after the first requestSession pooling keeps one connection aliveOpen a new connection or send Connection: close

requests reads HTTP_PROXY, HTTPS_PROXY, and NO_PROXY unless you disable it. An explicit proxies= argument wins for that request, but a CI shell with a corporate proxy variable can still change behavior between machines. Set session.trust_env = False so the code alone decides.

Verify the exit before the job

Send one request to an echo endpoint and log the IP and country. A 200 does not prove the proxy is in the path. A target can return 200 from your origin IP too, especially when a fallback path exists.

With socks5h, the hostname resolves at the exit, so assert the country you asked for. If the session silently falls back to another bucket, the dataset is corrupted without an error. Log the exit IP per request.

curl uses the same credentials

The session id and token work outside Python. In curl, the flag that matches socks5h is --socks5-hostname:

curl --socks5-hostname "$SESSION_ID:$TOKEN@api.proxybase.xyz:1082" \ https://api.ipify.org?format=json

--socks5 resolves DNS locally. --socks5-hostname hands the name to the exit, which is the behavior you want for the same reasons as socks5h.

What this setup does not fix

A proxy changes the exit IP and ASN. It does not change your TLS fingerprint, header order, request rate, or account permissions. If those are the signals getting you blocked, a different proxy type will fail the same way. Fix the request pattern first, then add exits.

The same limit applies legally. A proxy does not grant permission to access a site, bypass authentication or a paywall, or ignore robots rules and terms of service. If the plan only works because the target believes you are someone else, a proxy will not fix it.

Frequently Asked Questions

How do I use a SOCKS5 proxy with Python requests?

Install requests[socks], then pass a proxies dictionary to the request. Both the http and https keys point at the socks5h:// URL. Plain requests does not ship SOCKS support.

What is the difference between socks5 and socks5h?

socks5:// resolves the hostname locally, before the connection reaches the proxy. socks5h:// sends the hostname to the proxy and resolves it from the exit network. Use socks5h to avoid a DNS leak and to let the exit control the regional resolution.

Why do I get InvalidSchema: Missing dependencies for SOCKS support?

The installed requests package has no SOCKS support. Install the extra with pip install requests[socks]. Add the extra to your lockfile so a fresh environment does not reintroduce the error.

How do I pass a username and password to a SOCKS5 proxy?

Put them in the proxy URL: socks5h://username:password@host:port. PySocks reads them during the SOCKS handshake. HTTPProxyAuth is for HTTP proxy 407 responses and does nothing for SOCKS. URL-encode reserved characters.

Why does my rotating proxy only change IP once?

A requests.Session reuses TCP connections, and a rotating SOCKS session chooses a new seller per connection. Keep-alive therefore pins one exit. Use a new connection per request, send Connection: close, or recreate the Session periodically.

How do I set timeouts and retries?

Pass a tuple such as timeout=(5, 30) for connect and read limits, then mount an HTTPAdapter with a urllib3 Retry policy. Retry 429 and 5xx responses, never retry SOCKS authentication failures, and cap the total because retries consume billed bandwidth.

Related reading

Browse ProxiesCompare Mobile and Residential