Python · requests
Using a ProxyGuys proxy with the requests library
Most Python scripts that talk to the web start with requests, and pointing one at a ProxyGuys proxy takes a single dictionary. The same few lines work over HTTP or SOCKS5. Below you'll keep the login out of your source code, confirm which IP your traffic leaves from, and let the script ask for a fresh IP whenever it needs one. The library's own reference lives at requests.readthedocs.io.
What you need
- Python 3 with pip.
- The requests package, plus its
socksextra if you'll use the SOCKS5 port. - A started proxy. One you've just bought waits as Pending until you press Start proxy on My Proxies.
pip install requests
# only needed for the SOCKS5 port: pulls in PySocks
pip install "requests[socks]"Collect the connection details
Open My Proxies. The Connection column shows two addresses for each proxy, "HTTP proxy" and "SOCKS5 proxy". They share a host but use different ports, so note both. Under Credentials, Copy username copies the login name. The password stays masked until you press the eye button (Show / hide), and Copy password copies it.
Store those values as environment variables instead of pasting them into the script. They stay out of version control, and you can switch to another proxy without touching code:
# macOS / Linux (bash, zsh)
export PROXY_HOST="HOST"
export PROXY_HTTP_PORT="HTTP_PORT"
export PROXY_SOCKS5_PORT="SOCKS5_PORT"
export PROXY_USER="USERNAME"
export PROXY_PASS="PASSWORD"
# Windows PowerShell
$env:PROXY_HOST = "HOST"
$env:PROXY_HTTP_PORT = "HTTP_PORT"
$env:PROXY_SOCKS5_PORT = "SOCKS5_PORT"
$env:PROXY_USER = "USERNAME"
$env:PROXY_PASS = "PASSWORD"Send the first request through the proxy
requests picks a proxy by the scheme of the page you ask for, which is why the dictionary carries an http key and an https key pointing at the same proxy. Save this as check_proxy.py:
import os
from urllib.parse import quote
import requests
def proxy_url(protocol):
# Encode the login so characters such as # or % can't break the URL.
user = quote(os.environ["PROXY_USER"], safe="")
password = quote(os.environ["PROXY_PASS"], safe="")
host = os.environ["PROXY_HOST"]
if protocol == "socks5":
# socks5h: the proxy looks up hostnames, so DNS goes through it as well
return f"socks5h://{user}:{password}@{host}:{os.environ['PROXY_SOCKS5_PORT']}"
return f"http://{user}:{password}@{host}:{os.environ['PROXY_HTTP_PORT']}"
url = proxy_url(os.environ.get("PROXY_PROTOCOL", "http"))
proxies = {"http": url, "https": url} # one proxy for http:// and https:// pages
reply = requests.get(
"https://api.ipify.org", params={"format": "json"}, proxies=proxies, timeout=30
)
reply.raise_for_status()
print("This script now leaves from", reply.json()["ip"])Run it with python check_proxy.py. To try SOCKS5 instead, set PROXY_PROTOCOL to socks5 before running it (export PROXY_PROTOCOL=socks5, or $env:PROXY_PROTOCOL = "socks5" in PowerShell).
Reusing one session for many requests
A Session keeps connections open between calls and carries headers and cookies from one request to the next, which suits a script that fetches many pages. Give it the same proxies on every call:
# continues check_proxy.py, which defined proxies
session = requests.Session()
session.headers.update({"User-Agent": "price-watch/1.4", "Accept-Language": "en-US"})
for target in ("https://httpbin.org/ip", "https://httpbin.org/headers"):
r = session.get(target, proxies=proxies, timeout=30)
print(target, r.status_code, len(r.content), "bytes")Why not set session.proxies once and forget it? requests gives proxy variables from your environment (HTTP_PROXY, HTTPS_PROXY) priority over session.proxies, so a proxy configured elsewhere on the machine could quietly take over. Passing proxies= with each call keeps your ProxyGuys proxy in charge.
Ask for a new IP from your script
On the API page, press Create key. The key is shown only once, so store it right away. You also need the proxy's API id, which looks like pp123456 and is not the same as its login; a GET request to https://proxyguys.com/api/v1/proxies with your key lists your proxies.
export PROXYGUYS_API_KEY="YOUR_API_KEY"
export PROXYGUYS_PROXY_ID="pp123456"The rotate call keeps the city and carrier and replies once the change has finished. That usually takes 30 to 90 seconds, hence the long timeout. The new_ip field in the reply can be null; if it is, read the IP from the echo service instead. Asking again within 60 seconds returns a 409 with "code": "cooldown" and a retry_after value in seconds, which the function below waits out.
import os
import time
import requests
API = "https://proxyguys.com/api/v1"
AUTH = {"Authorization": "Bearer " + os.environ["PROXYGUYS_API_KEY"]}
def rotate(proxy_id, attempts=3):
# New IP in the same city and on the same carrier. Returns it, or None.
for _ in range(attempts):
r = requests.post(f"{API}/proxies/{proxy_id}/rotate", headers=AUTH, timeout=150)
body = r.json()
if r.status_code == 409 and body.get("code") == "cooldown":
wait = float(body.get("retry_after", 60))
print(f"cooling down, trying again in {wait:.0f} s")
time.sleep(wait)
continue
if not r.ok:
raise RuntimeError(f"rotate failed ({r.status_code}): {body.get('error')}")
return body.get("new_ip")
raise RuntimeError("still cooling down after several tries")
print("new IP:", rotate(os.environ["PROXYGUYS_PROXY_ID"]))Rather not handle an API key? Open the proxy's ⋮ menu (More actions on smaller screens) and choose Copy change-IP link. Put it in an environment variable, and requests.get(os.environ["PROXY_CHANGE_IP_URL"], timeout=150) changes the IP. Its reply can take as long as the change itself, which is why the timeout is generous. The link needs no login, so anyone who has it can use it: keep it as private as a password, and use New change-IP link if it leaks. It also allows one change every 60 seconds. The rotation guide covers the timed options as well.
Confirm it works
First see your own address by fetching the echo service without any proxy:
python -c "import requests; print(requests.get('https://api.ipify.org', timeout=30).text)"Then run check_proxy.py. The two addresses should differ. If a lookup site places the proxy's IP in a different city or state from the one you picked, that's expected: each lookup site uses its own database, and mobile IPs often show up somewhere else.
When it doesn't connect
- A ProxyError that mentions 407. The proxy refused the login. Copy the password again with Copy password and check the environment variable for stray spaces or quote marks. If you changed it with New password, make sure the script picked up the new one.
- InvalidSchema: Missing dependencies for SOCKS support. Install the extra with
pip install "requests[socks]". - A dropped connection, a SOCKS error or a timeout straight away. The scheme and the port don't match.
http://goes with the HTTP port andsocks5h://with the SOCKS5 port. The line under ⋮ → Details ends in the SOCKS5 port, so it won't work withhttp://. - Connecting from a whitelisted IP. Whitelisted addresses use a separate whitelist port shown in the IP whitelist window, with no username or password. Copy endpoint gives you its host and port: put
http://orsocks5h://in front, matching the Protocol you picked, and leave the login out. See the IP whitelist guide.
Still stuck? A GET request to https://proxyguys.com/api/v1/proxies/pp123456?probe=true (with your API key) test-dials the proxy. You can also open a ticket from Tickets in the dashboard or write to support@proxyguys.com.