ScrapingAutomationProxies

How to Use Residential Proxies with Playwright (2026)

AE
Engineering desk
Published
August 22, 2026
Updated
September 19, 2026
Reviewed by
Read Time
5 min read
Diagram of a Playwright browser, context, and page with a residential proxy on the context

A Playwright residential proxy is a Playwright browser context whose every request — document, XHR, WebSocket upgrade — leaves through an IP that an ISP assigned to a household, not through the machine that launched Chromium. You configure it with a proxy object: server, username, password. You do not embed user:pass@host in the server string. Chromium strips that userinfo and answers 407, which looks like a network failure and wastes a morning.

This is the long guide. The copy-paste card lives at /integrations/playwright. If the page loaded and the scraper still “succeeded” with empty HTML, that is a different bug: Playwright silent 403.

Why Playwright needs a residential exit

Playwright already looks more like a browser than requests does. That does not make the exit IP look like a household. Launching Chromium on a GitHub runner, an AWS box, or a Hetzner VPS still presents a datacenter ASN. CDNs classify that ASN in the handshake. A stealth plugin will not rewrite the autonomous system. Pairing Playwright with a datacenter proxy is the most common expensive mistake in 2026: you pay for a full browser and then donate the session to a range that Cloudflare already scored as automation.

A residential exit changes the trust class. Aethyn Premium (proxy.aethyn.io:2099) is the volume pool with country targeting. Elite (:5499) adds city and ISP when the target is hard. Both are residential; Aethyn does not sell a datacenter SKU to “try first.” If the page is unprotected, you may not need a browser at all — see residential vs datacenter. If you are already in Playwright, put a residential IP on the context.

Launch sets a placeholder; each context gets its own proxy
Chromium ignores per-context proxies unless launch() already has a proxy. Use Playwright’s per-context placeholder, then set the real gateway on each context.

Credentials go in fields, never in the URL

Three fields — server, username, password — not user:pass@host
Chromium strips inline proxy credentials. 407 is almost always this, not a dead gateway.

Python:

Code Snippet
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={"server": "per-context"})
    context = browser.new_context(
        proxy={
            "server": "http://proxy.aethyn.io:2099",
            "username": "aethyn-XXXXX-country-us",
            "password": "PASSWORD",
        }
    )
    page = context.new_page()
    page.goto("https://httpbin.org/ip")
    print(page.content())
    context.close()
    browser.close()

Node.js:

Code Snippet
import { chromium } from "playwright";

const browser = await chromium.launch({ proxy: { server: "per-context" } });
const context = await browser.newContext({
  proxy: {
    server: "http://proxy.aethyn.io:2099",
    username: "aethyn-XXXXX-country-us",
    password: "PASSWORD",
  },
});
const page = await context.newPage();
await page.goto("https://httpbin.org/ip");
console.log(await page.content());
await context.close();
await browser.close();

Replace aethyn-XXXXX and PASSWORD from the dashboard. Elite HTTP is port 5499; Premium SOCKS5 is socks5://proxy.aethyn.io:1099. Targeting suffixes live on the username: country, optional city/ISP (Elite), optional -session-ID-lifetime-N.

The short integration card at /integrations/playwright launches with the proxy on chromium.launch() — that is correct when every context shares one exit. The placeholder pattern above is what you need for many identities in one process.

Rotate by creating a new context

One context equals one identity
Cookies and the exit IP are bound to the context. Rotate by closing it, not by flipping a URL.

Playwright reads proxy when the context is created. There is no context.setProxy() that you call mid-job. Per-request rotation on a rotating residential gateway happens because each new TCP connection can draw a new IP — but a browser context reuses connections, cookies, and service workers. If you need a fresh identity, close the context and open another with a new -session- token (or omit session for a random exit). If you need the same identity across pagination, put -session-job42-lifetime-30 on the username and keep that context alive for the job.

Sticky lifetime on Aethyn is 1–1440 minutes. Default is 30 if you omit -lifetime-N. That is a gateway hold, not a Playwright setting. When the TTL expires, the next request on that session id may land on a new household. Build a retry that opens a fresh context rather than assuming the IP is nailed to the wall for 24 hours.

Match locale, timezone, and geolocation to the exit

Exit country must equal locale, timezone, and geolocation
A US residential IP with a Tokyo timezone is a fingerprint mismatch. Set them together.

A US Elite exit with locale: "ja-JP" and a Tokyo timezone is a gift to bot management. Set locale, timezoneId, and geolocation (plus permissions) to the country you encoded in the username. Keep the User-Agent and viewport stable for the life of that context. Switching UA on a sticky IP is a louder tell than rotating the IP under a stable UA.

Python sketch:

Code Snippet
context = browser.new_context(
    proxy={
        "server": "http://proxy.aethyn.io:5499",
        "username": "aethyn-XXXXX-country-us-city-newyork-session-nyc1-lifetime-30",
        "password": "PASSWORD",
    },
    locale="en-US",
    timezone_id="America/New_York",
    geolocation={"longitude": -74.006, "latitude": 40.7128},
    permissions=["geolocation"],
)

City and ISP suffixes require Elite. Premium is country-only. If the city does not resolve, the tunnel falls back to the country — see targeting docs.

Save gigabytes (you pay for them)

Playwright will happily download every image, font, and tracker. On residential, that is the bill. Abort what the parser does not need:

Code Snippet
context.route("**/*.{png,jpg,jpeg,gif,webp,svg,woff,woff2}", lambda route: route.abort())

Then measure cost per successful request on a sample. A headed run that loads a 4 MB homepage to extract one JSON blob is how teams “prove” residential is expensive.

Troubleshooting

SymptomLikely causeFix
407Credentials in the URL, or username/password swappedFields only; rebuild from the dashboard
Context proxy ignoredLaunched Chromium with no proxylaunch({ proxy: { server: "per-context" } })
net::ERR_TUNNEL_CONNECTION_FAILEDWrong port or schemeHTTP 2099/5499; SOCKS5 1099/3499
Page 200, empty/challenge bodySoft blockAssert selectors; see silent 403
Works once, then 403Sticky reused too hard, or datacenter leftoverNew context; Elite if Premium is scored

Do not throw both IP tier and fingerprint stack in one panic change. Change one, measure, then the other. If the document does not need JavaScript, run the curl_cffi vs requests vs Playwright protocol before you scale Chromium. Public-data collection only — this page does not teach CAPTCHA solving.

Start free trial

FAQ

Common questions about this article

How do I set a proxy in Playwright?
Pass a proxy object with server, username, and password. Put credentials in those fields — Chromium strips user:pass from a URL and you get 407. For per-context proxies on Chromium, launch with a placeholder proxy: { server: 'per-context' }, then set the real proxy on each browser.newContext().
Why is my Playwright per-context proxy ignored?
Chromium only honours context-level proxies if the browser was launched with a proxy already set. Launch with proxy: { server: 'per-context' } (Playwright’s placeholder), then pass the real Aethyn server and credentials on newContext(). Launching with no proxy makes every context proxy silently no-op.
Should I rotate IPs inside one Playwright context?
No. A context owns cookies, storage, and the proxy. Rotate by closing the context and opening a new one with a new session id (or no session id). Mutating a live context’s proxy is not supported; reusing a context across identities leaks cookies onto a new exit.
How long can a Playwright sticky session last on Aethyn?
Sticky lifetime is 1–1440 minutes (24 hours). Default is 30 minutes if you omit -lifetime-N. Encode it on the username: aethyn-XXXXX-country-us-session-job42-lifetime-30. Same session id inside the window reuses the exit.
Does Playwright work with SOCKS5 residential proxies?
Yes. Set server to socks5://proxy.aethyn.io:1099 (Premium) or socks5://proxy.aethyn.io:3499 (Elite) and keep username/password in the fields. Most teams use the HTTP CONNECT port (2099 / 5499) unless the client specifically needs SOCKS5.
Share this article

Guides, integrations & docs

Continue reading

Run Playwright through real household IPs

Premium HTTP 2099 for volume. Elite 5499 when the target scores the exit. Sticky 1–1440 minutes in the username. Free trial, no card.

Back to all articles