Python · Playwright
Playwright for Python over a ProxyGuys proxy
Playwright drives real browsers, so everything a page loads (HTML, scripts, images, API calls) goes through whatever proxy the browser is given. That proxy is a small dictionary passed when you launch the browser or open a context. These examples use the synchronous API; the async one takes the same dictionary. Playwright's Python docs are at playwright.dev/python.
Use the HTTP port
Playwright's username and password options are documented for HTTP proxies, so the dependable setup is the HTTP port with your login. If you need SOCKS5 in the browser, whitelist your IP with the Protocol set to SOCKS5 and point server at the whitelist endpoint with no login (see the IP whitelist guide). Playwright's documented SOCKS form for server is socks5://.
Install
pip install playwright
# download a browser build for Playwright (firefox and webkit work the same way)
playwright install chromiumRead your proxy details into the environment
On My Proxies, check that the proxy has been started. A new one shows Pending until you press Start proxy.
From the "HTTP proxy" box in the Connection column, take the host and the HTTP port. The "SOCKS5 proxy" box uses a different port; ignore it here.
Under Credentials, use Copy username and Copy password (the eye button, Show / hide, reveals the password if you want to check it).
Export the four values. In PowerShell, write
$env:PROXY_HOST = "HOST"and so on.export PROXY_HOST="HOST" export PROXY_HTTP_PORT="HTTP_PORT" export PROXY_USER="USERNAME" export PROXY_PASS="PASSWORD"
One proxy for the whole browser
Because username and password are separate keys, special characters in the password need no encoding. The same PROXY dictionary works for p.firefox and p.webkit.
import os
from playwright.sync_api import sync_playwright
PROXY = {
"server": f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_HTTP_PORT']}",
"username": os.environ["PROXY_USER"],
"password": os.environ["PROXY_PASS"],
}
with sync_playwright() as p:
browser = p.chromium.launch(proxy=PROXY) # or p.firefox / p.webkit
page = browser.new_page()
page.goto("https://api.ipify.org?format=json", timeout=60_000)
print("browser exit IP:", page.inner_text("body"))
browser.close()The printed IP should not be yours. Lookup sites may report it in a different city or state than the location you picked, since every site uses its own database; with mobile IPs that's normal.
A different proxy for each context
A browser context is an isolated session with its own cookies and storage. Giving each context its own proxy lets one browser run several ProxyGuys proxies side by side, say one per account you manage. Store each proxy's values under its own prefix. The browser itself starts without a proxy, as in Playwright's own per-context example, and every context brings its own.
import os
from playwright.sync_api import sync_playwright
def proxy_from_env(prefix):
# reads e.g. SHOP_A_HOST, SHOP_A_HTTP_PORT, SHOP_A_USER, SHOP_A_PASS
return {
"server": f"http://{os.environ[prefix + '_HOST']}:{os.environ[prefix + '_HTTP_PORT']}",
"username": os.environ[prefix + "_USER"],
"password": os.environ[prefix + "_PASS"],
}
with sync_playwright() as p:
browser = p.chromium.launch() # no browser-wide proxy: each context sets its own
for prefix in ("SHOP_A", "SHOP_B"):
context = browser.new_context(proxy=proxy_from_env(prefix))
page = context.new_page()
page.goto("https://httpbin.org/ip")
print(prefix, page.inner_text("body"))
context.close()
browser.close()New IP between rounds, using Playwright's request API
Playwright ships its own HTTP client (p.request), so calling the ProxyGuys API needs no extra package. Create a key with Create key on the API page; it is displayed once, so save it. Set it as PROXYGUYS_API_KEY, and set PROXYGUYS_PROXY_ID to the proxy's API id (it looks like pp123456 and is not the login).
Each rotate call keeps the city and carrier and returns when the change is done, usually within 30 to 90 seconds. A call within 60 seconds of the previous change gets a 409 with "code": "cooldown" and a retry_after in seconds, which the helper sleeps through.
import os
import time
from playwright.sync_api import sync_playwright
API = "https://proxyguys.com/api/v1"
PROXY = {
"server": f"http://{os.environ['PROXY_HOST']}:{os.environ['PROXY_HTTP_PORT']}",
"username": os.environ["PROXY_USER"],
"password": os.environ["PROXY_PASS"],
}
def rotate(api, proxy_id, attempts=4):
for _ in range(attempts):
# The API replies once the new IP is ready: allow up to 150 s (value in ms).
resp = api.post(f"{API}/proxies/{proxy_id}/rotate", timeout=150_000)
data = resp.json()
if resp.status == 409 and data.get("code") == "cooldown":
time.sleep(float(data.get("retry_after", 60)))
continue
if not resp.ok:
raise RuntimeError(f"rotate failed ({resp.status}): {data.get('error')}")
return data.get("new_ip") # may be None
raise RuntimeError("cooldown never cleared")
with sync_playwright() as p:
api = p.request.new_context(
extra_http_headers={"Authorization": "Bearer " + os.environ["PROXYGUYS_API_KEY"]}
)
browser = p.chromium.launch(proxy=PROXY)
for round_no in range(1, 4):
context = browser.new_context() # starts without cookies from the last round
page = context.new_page()
page.goto("https://api.ipify.org?format=json", timeout=60_000)
print(f"round {round_no}:", page.inner_text("body"))
context.close()
print("rotated, API reports", rotate(api, os.environ["PROXYGUYS_PROXY_ID"]))
browser.close()
api.dispose()Prefer a link to an API key? ⋮ → Copy change-IP link gives a URL that changes the IP when opened; p.request.new_context().get(link, timeout=150_000) opens it without sending your API key along (the reply can take as long as the change, hence the timeout). Anyone holding the link can change your IP, so keep it private. More options are in Changing and rotating IPs.
If pages won't load
- net::ERR_PROXY_CONNECTION_FAILED or ERR_TUNNEL_CONNECTION_FAILED. The browser couldn't use the proxy. Check the host and that the port is the HTTP one; the ⋮ → Details line contains the SOCKS5 port, which won't work with
http://. - An authentication error or a 407. Copy the password again with Copy password. If you changed it with New password, update
PROXY_PASS. - goto() times out. Raise its
timeoutwhile testing, and confirm the proxy shows Running on My Proxies. - SOCKS5 with a username and password won't connect. Switch to the HTTP port, or whitelist your IP and connect to the whitelist endpoint without a login.