How to Use Proxies in Playwright 2026
Learn how to use proxies in Playwright with copy-paste code: basic setup, authentication, per-context proxies, rotation, JavaScript, and the best providers to use.
You can write a flawless Playwright scraper and still watch it fail within minutes — not because of a bug, but because the target site blocked your IP address. With automated traffic now making up nearly half of all web activity according to Imperva, websites are quick to throttle or ban any single address that behaves like a bot.
The fix is proxies. By routing Playwright through proxy servers, you change the IP address websites see, spread requests across many addresses, and unlock geo-specific content. The best part is that Playwright has proxy support built right in.
This guide shows you exactly how to use proxies in Playwright in 2026 — basic setup, authentication, per-context proxies, rotation, and the same in JavaScript — all with copy-paste code. Let us make your scrapers unblockable.
Why Use Proxies in Playwright?
A proxy is an intermediary server that forwards your requests, so the target website sees the proxy IP instead of yours. In a Playwright workflow, that delivers three big wins.
First, it prevents IP bans — spreading requests across many IPs means no single address trips a rate limit. Second, it unlocks geo-targeting, letting you view a site as a user in another country. Third, it adds a layer of privacy by hiding your real address. For scraping at any real scale, proxies are not optional.
Types of Proxies for Playwright
Not all proxies are equal, and the type you choose has a big impact on success rates and cost.
| Type | Looks like | Best for |
|---|---|---|
| Datacenter | A server in a data center | Speed and volume on lenient sites |
| Residential | A real home internet user | Hard targets that block bots |
| Mobile | A real mobile device | The strictest sites and apps |
| ISP | A static residential IP | Speed plus a residential reputation |
Datacenter proxies are fast and cheap but easier to detect. Residential and mobile proxies look like genuine users and are far harder to block, at a higher price. Match the type to how aggressively your target fights bots.
Setting Up a Proxy in Playwright
The simplest way is to pass a proxy when you launch the browser. Every request then routes through it. We will test against httpbin, which returns the IP it sees.
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(
proxy={"server": "http://proxy.example.com:8080"}
)
page = browser.new_page()
page.goto("https://httpbin.org/ip")
print(page.inner_text("body")) # shows the proxy IP, not yours
browser.close()Proxy Authentication (Username and Password)
Most commercial proxies require credentials. Playwright handles this cleanly with username and password fields in the same proxy object — no awkward workarounds like older tools need.
browser = p.chromium.launch(
proxy={
"server": "http://gate.provider.com:7000",
"username": "YOUR_USERNAME",
"password": "YOUR_PASSWORD",
}
)Never hard-code real credentials in shared code. Load them from environment variables or a secrets file so they do not leak into version control.
Per-Context Proxies: The Key to Rotation
Here is the most important concept for scraping. Instead of one proxy for the whole browser, you can give each browser context its own proxy. A context is an isolated session with its own cookies and storage, which makes it perfect for running multiple identities.
with sync_playwright() as p:
browser = p.chromium.launch()
# Each context can use a different proxy and its own storage
context = browser.new_context(
proxy={"server": "http://gate.provider.com:7000",
"username": "USER", "password": "PASS"}
)
page = context.new_page()
page.goto("https://httpbin.org/ip")
print(page.inner_text("body"))
context.close()
browser.close()Where you set the proxy matters, so here is a quick reference:
| Set proxy at | Scope | Use for |
|---|---|---|
| launch() | The whole browser | A single proxy for everything |
| new_context() | One isolated session | Different proxy per identity, rotation |
Rotating Proxies in Playwright
To rotate, give each context a different proxy from your pool. Close the context between jobs so cookies do not bleed across identities.
import random
from playwright.sync_api import sync_playwright
PROXIES = [
{"server": "http://198.51.100.1:8000", "username": "u", "password": "p"},
{"server": "http://198.51.100.2:8000", "username": "u", "password": "p"},
{"server": "http://198.51.100.3:8000", "username": "u", "password": "p"},
]
urls = ["https://httpbin.org/ip", "https://httpbin.org/ip", "https://httpbin.org/ip"]
with sync_playwright() as p:
browser = p.chromium.launch()
for url in urls:
proxy = random.choice(PROXIES)
context = browser.new_context(proxy=proxy)
page = context.new_page()
page.goto(url)
print(page.inner_text("body")) # a different IP per context
context.close()
browser.close()For more on building robust rotation logic with retries and health checks, see our dedicated guide on building a rotating proxy script.
Using a Rotating Gateway (the Easier Way)
Managing a proxy list is work. Most premium providers offer a single rotating endpoint that hands you a fresh IP automatically, so you set it once and forget the list entirely.
# One gateway endpoint rotates the IP for you on each new connection
browser = p.chromium.launch(
proxy={"server": "http://gate.provider.com:7000",
"username": "USER", "password": "PASS"}
)
# Open a new context for each job to pick up a fresh IP
context = browser.new_context()Using Proxies in Playwright with JavaScript
Prefer Node.js? The API is nearly identical. Pass the same proxy object when you launch Chromium.
// npm i playwright
import { chromium } from "playwright";
const browser = await chromium.launch({
proxy: {
server: "http://gate.provider.com:7000",
username: "USER",
password: "PASS",
},
});
const page = await browser.newPage();
await page.goto("https://httpbin.org/ip");
console.log(await page.innerText("body"));
await browser.close();Verifying Your Proxy Works
Always confirm the proxy is active before a real run. Load httpbin.org/ip and check that the returned address is the proxy, not your own. If you see your real IP, the proxy is not being applied — recheck the server format and credentials. For geo-checks, compare the reported country against what you expect from the proxy location.
Best Proxies to Use with Playwright
Playwright proxy support is only as good as the network behind it. Free proxies are slow and short-lived; for serious scraping, a quality paid provider is essential. These are the ones we rate most highly.
Decodo
Decodo offers a large residential pool with a rotating gateway that drops straight into the launch code above, plus a friendly dashboard for managing endpoints and sticky sessions.
Its blend of price, reliability, and ease of use makes it a great default for Playwright users who want rotation that simply works.
Oxylabs
Oxylabs is the enterprise option, with a massive pool, excellent geo-targeting, and rotating endpoints built for heavy, sustained scraping.
It costs more, but for large jobs where success rate and uptime matter most, the reliability is worth the premium.
IPRoyal
IPRoyal is the value pick, well known for non-expiring traffic that suits intermittent Playwright jobs where unused bandwidth should not vanish each month.
It offers both rotating and sticky residential sessions at approachable prices, ideal for individuals and smaller projects.
Webshare
Webshare is the developer favorite for affordable proxies, with a free tier that is perfect for testing your Playwright proxy setup before you spend a cent.
Its clean API lets you pull proxies programmatically, which pairs nicely with the rotation pattern shown earlier.
Handling Proxy Errors and Retries
Proxies fail — they time out, get blocked, or simply die. A production Playwright scraper must catch these errors, switch to a fresh proxy, and retry instead of crashing on the first failure.
The pattern is to wrap your navigation in a try block, and on failure close the current context, pick a new proxy, and try again a few times.
import random
from playwright.sync_api import sync_playwright
def goto_with_retry(browser, url, proxies, attempts=3):
for attempt in range(attempts):
context = browser.new_context(proxy=random.choice(proxies))
page = context.new_page()
try:
page.goto(url, timeout=15000)
return page, context # success
except Exception:
context.close() # rotate and retry
raise RuntimeError(f"All {attempts} proxies failed for {url}")This simple wrapper turns transient proxy failures into non-events, which is the difference between a scraper that finishes a run and one that dies halfway through.
Geo-Targeting with Proxies in Playwright
One of the most powerful uses of proxies is appearing in a specific country. Pricing, search results, and content often differ by region, and a proxy in the right location lets Playwright see exactly what a local user sees.
Most providers expose geo-targeting through the proxy username or a country-specific endpoint — for example, adding a country code to the username string. You keep the same Playwright code and simply swap the credentials or server to change location.
After setting a geo-targeted proxy, always verify it by loading a page that reports your detected location, confirming Playwright is really browsing from the country you intended before you rely on the data.
Datacenter vs Residential Proxies for Playwright
The most common question is which proxy type to use, and the honest answer is that it depends on your target. Datacenter proxies are fast and inexpensive, making them ideal for high-volume scraping of sites that do not aggressively fight bots.
Residential proxies route through real home devices, so they look like genuine users and slip past strict anti-bot systems that instantly flag datacenter ranges. The trade-off is higher cost and slightly more latency.
A practical strategy is to start with datacenter proxies for speed, and only escalate to residential or mobile when you see blocks. Many Playwright scrapers use a mix, sending easy requests through datacenter IPs and reserving residential ones for the hardest pages.
Proxy Pool or Rotating Gateway: Which Is Simpler?
You have two ways to manage proxies in Playwright. A self-managed pool gives you a list of individual proxies that you rotate across contexts in code, offering full control and working well with cheaper datacenter proxies.
A rotating gateway is a single endpoint from a provider that changes the IP for you automatically. You set it once and never touch a list, which is far simpler at scale and the reason most teams choose it for large jobs. For small, controlled runs the pool approach is fine; for volume, the gateway wins.
Common Mistakes When Using Proxies in Playwright
A few recurring errors trip people up. Avoid these and your proxied scrapers will be far more reliable.
Wrong server format
The server value must include the scheme, like http or socks5, and the port. Leaving off the protocol or port is the most common reason a proxy silently fails to apply.
Rotating the IP but not the session
Changing the proxy while reusing the same context keeps the old cookies, which can link your identities. Open a fresh context per proxy so each session is genuinely independent.
Mismatching proxy type to the target
Using cheap datacenter IPs on a site that demands residential ones leads to instant blocks. Match the proxy type to how aggressively the target fights bots.
Hammering the site too fast
Proxies are not a license to flood a server. Add randomized delays between requests, because even rotated IPs get flagged when traffic is inhumanly fast.
Leaving credentials in your code
Hard-coded proxy credentials leak into version control and logs. Always load them from environment variables or a secrets manager instead.
SOCKS5 vs HTTP Proxies in Playwright
Playwright supports both HTTP and SOCKS5 proxies, and the difference occasionally matters. HTTP proxies are the most common and work for virtually all web scraping. SOCKS5 proxies operate at a lower level and can carry any protocol, which is useful for non-HTTP traffic.
For Playwright scraping, an HTTP or HTTPS proxy is almost always the right choice. Just set the scheme correctly in the server value, and reach for socks5 only when your provider specifically issues SOCKS endpoints.
Best Practices for Proxies in Playwright
- Use per-context proxies to keep each identity isolated and rotatable.
- Verify before you scrape by checking httpbin.org/ip on every fresh setup.
- Match the proxy type to your target — residential for strict sites, datacenter for speed.
- Pace your requests with randomized delays even when rotating IPs.
- Choose a quality provider — compare options in our proxy directory and our best proxies for Playwright guide.
Frequently Asked Questions
The Bottom Line
Using proxies in Playwright is straightforward because support is built in: pass a proxy object at launch for a single IP, or per context for rotation and isolation. Add credentials inline, verify against httpbin, and match the proxy type to your target.
Once you are comfortable with the setup, the only thing left is choosing a strong network. Pair Playwright with a quality provider from our proxy directory, see our best proxies for Playwright roundup, and revisit the full Playwright scraping guide to put it all together.
Keep Reading
More articles you might enjoy