INTEGRATIONS

How to use a proxy with Python requests

Point requests at one static ISP address: a single IP on a named internet provider's network, kept for the period you pay for. The code below was run against an authenticated proxy before it was published.

Browse the catalogue All integrations

In short: Pass a proxies dictionary with both the http and https keys, each set to http://USERNAME:PASSWORD@HOST:PORT, and requests sends the call through the proxy; HTTPS targets go through it as a tunnel. For SOCKS5, install requests[socks], switch the proxy to SOCKS5 on your order and use the socks5h scheme, so the proxy resolves hostnames instead of your machine.

Python requests takes its proxy from a dictionary that maps the scheme of the target URL to a proxy URL. This guide sets that dictionary for one static ISP address and shows the three places it can live: on a call, on a session, or in the environment.

Python requests proxy with a username and password

Most proxies, ours included, ask for a username and password. requests reads them from the proxy URL and sends them to the proxy on every connection. For an HTTPS target the proxy opens a tunnel and never sees the content of the request. The code tabs show the per-request and the session form.

STEP BY STEP

Set a proxy in Python requests

Copy the four values from your order
Host, port, username and password, from My Proxies in the dashboard or from the order in the API. Each address has its own four; there is no shared gateway.
Build one proxy URL
http://USERNAME:PASSWORD@HOST:PORT. If the password contains /, ?, # or %, URL-encode it first with urllib.parse.quote(password, safe="").
Set it for both schemes
Give the same URL to the http and the https key. With only http set, every HTTPS request skips the proxy and leaves from your own address.
Check the exit address once
Request a page that shows the caller’s IP, or open What Is My IP through the same proxy, and confirm it is the address you bought.
Run the job with a timeout
Always pass timeout=: requests waits forever by default, and a stalled connection then looks like a hung script.

Per request Session SOCKS5

import requests

# The four values come with your order (dashboard or API)
proxy = "http://USERNAME:PASSWORD@HOST:PORT"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
response.raise_for_status()
print(response.status_code)

import requests

proxy = "http://USERNAME:PASSWORD@HOST:PORT"

with requests.Session() as session:
    # HTTP_PROXY / HTTPS_PROXY in the environment would override
    # session.proxies; this makes the session use only its own setting.
    session.trust_env = False
    session.proxies.update({"http": proxy, "https": proxy})
    response = session.get("https://example.com/", timeout=30)
    response.raise_for_status()
    print(response.status_code)

# pip install "requests[socks]"
import requests

# Switch the proxy to SOCKS5 first; use the values the order then shows.
# socks5h: the proxy resolves the hostname, not your machine.
proxy = "socks5h://USERNAME:PASSWORD@HOST:PORT"

response = requests.get(
    "https://example.com/",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
response.raise_for_status()
print(response.status_code)

CODE

Tested code for requests

Each sample connects through an HTTP proxy with a username and password, except the SOCKS5 one, which needs the proxy switched to SOCKS5 first; the order then shows a new port and new credentials to use. Replace the four capitals with your order's values.

Full API docs

Per request Pass the proxy to one call. Session Set the proxy once for every call in a session. SOCKS5 SOCKS5 with hostnames resolved at the proxy.

OPTIONS

Where the proxy can be set in requests

Read from the requests documentation and checked with this page's code samples against a local authenticated proxy. When more than one is set, a proxies argument on the call wins over the environment, and the environment wins over Session.proxies unless the session sets trust_env to False, as the Session sample does.
	Scope	Credentials	When to use it
proxies= on a call	That one request	In the URL	A script with a handful of calls
Session.proxies	Every request of the session	In the URL	Anything longer, with trust_env set to False
HTTP_PROXY and HTTPS_PROXY	Every requests call in the process	In the URL	Code you cannot edit; NO_PROXY lists the hosts to skip
socks5h:// URL	Whatever scope it is set at	In the URL	When hostnames should be resolved at the proxy

COMMON MISTAKES

What goes wrong with requests and proxies

Only the http key is set

The key names the scheme of the target, not of the proxy. A dictionary with only http routes plain HTTP and lets every HTTPS call go out directly, with no error to tell you.

socks5 where socks5h was meant

With socks5 your machine resolves the hostname and hands the proxy an IP. With socks5h the proxy resolves it, so the lookup and its answer come from the proxy's network, which matters for sites that answer by location.

A password that breaks the URL

A slash, question mark or hash in the password cuts the URL short, and requests fails before it reaches the proxy; a percent sign is decoded as an escape. URL-encode the password, or use IP whitelist authentication and leave the credentials out.

An environment variable you forgot

requests reads HTTP_PROXY, HTTPS_PROXY and NO_PROXY unless you set trust_env to False on the session, and those variables override Session.proxies. A stale variable on a server can send a session's traffic somewhere you did not intend, or around the proxy.

THE ADDRESS

What requests connects to

Protocols: HTTP, which carries HTTPS, or SOCKS5, switched on the order
Authentication: Username and password, or an IP whitelist set through the API
Address: One static IP for the period, on a named internet provider's network
Rotation: None: the same address on every request

Selenium A proxy for a browser driven by Selenium

Playwright A proxy per browser or per context

SOCKS5 Proxies The protocol, and how to switch to it

ISP Proxies The static addresses these guides use

FAQ

Questions about proxies in Python requests

How do I use a proxy with authentication in Python requests?

Put the username and password in the proxy URL, http://USERNAME:PASSWORD@HOST:PORT, and pass it for both the http and https keys. requests sends the credentials to the proxy, which answers 407 if they are wrong. Encode a password that contains reserved characters, or use an IP whitelist instead.

How do I use a SOCKS5 proxy with requests?

Install the extra with pip install requests[socks], switch the proxy itself to SOCKS5 on your order, and use the port and credentials the order then shows in a socks5h:// URL. Changing the scheme alone is not enough: an address set to HTTP does not answer SOCKS5 until it is switched. SOCKS5

Can I use IP whitelist authentication instead of a password?

Yes. Add the public IPv4 address your script runs from to the proxy's whitelist with one API call, PUT /orders/ORDER_ID/whitelist, or through the MCP server; the dashboard has no control for it yet. The proxy then accepts connections from that address without credentials, over HTTP and over SOCKS5, and the URL becomes http://HOST:PORT. While a whitelist is set, the proxy admits only the listed addresses and the username and password stop working for that order; sending an empty list turns the whitelist off and password login works again.

Does the address rotate between requests?

No. A static ISP proxy is one address for the period you pay for, and every request you send through it leaves from that address. If a job needs a different address per request, that is a rotating pool, which we do not sell yet.

How do I check which IP a site sees?

Request a page that echoes the caller's address through the same proxy, or open What Is My IP from a browser set to it. If it shows your own address, the https key is probably missing. What Is My IP

What can I use the proxy for?

Testing your own sites by region, quality checks, ad verification, price and market research and brand protection need no review under our acceptable use policy. The proxy does not get around CAPTCHAs, bot detection, rate limits or account bans, and the policy forbids using it to try. Acceptable Use Policy

A static address suits jobs that should arrive from the same place each time: a monitor, a regional check, a test that compares today with last week. Order one address per job on ISP proxies, see pricing, and if the same job runs in a browser, the Selenium and Playwright guides set the same address there.

Sources

Requests documentation, Proxies: the proxies argument, environment variables and SOCKS support
RFC 1928, SOCKS Protocol Version 5: how a client asks a SOCKS5 proxy for a destination by name or by address
RFC 3986, URI Generic Syntax: the userinfo part of a URL and the characters that must be encoded in it

How to use a proxy with Python requests

Python requests proxy with a username and password

Set a proxy in Python requests

Copy the four values from your order

Build one proxy URL

Set it for both schemes

Check the exit address once

Run the job with a timeout