Playwright with Proxies: Complete 2026 Setup Guide

By Elena Park · 2026-05-13 · 14 min read · Engineering

Playwright + residential proxies is the modern stealth scraping stack. Here's the full 2026 setup with working code.

Playwright with proxies: the short answer

Playwright supports proxies natively through a proxy option passed at browser launch or per browser context, accepting a server URL plus optional username and password for authenticated gateways. For most production scraping in 2026, the recommended setup pairs Playwright with a residential proxy gateway like Bright Data's, one proxy configuration per browser context so each context gets its own rotating IP, combined with stealth patches to address the fingerprint signals proxies alone do not solve.

Proxies address only the network layer - your IP address and its reputation. Playwright's default Chromium, Firefox and WebKit instances still expose automation-detectable signals at the JavaScript and TLS level that must be patched separately for reliable success against protected sites.

Basic setup

The simplest way to launch Playwright with a proxy is to pass the proxy object directly to browser.launch or browser.newContext, specifying the server address, and if required, username and password for authenticated gateways like Bright Data's.

• browser = await playwright.chromium.launch(proxy={"server": "http://brd.superproxy.io:22225", "username": "user", "password": "pass"})
• context = await browser.new_context()
• page = await context.new_page(); await page.goto("https://example.com")

Per-context proxies (rotation)

For workloads that need different IPs across parallel tasks, set the proxy at the context level rather than the browser level - this lets you launch one browser instance and open multiple contexts, each with its own proxy configuration and its own isolated cookies and storage, which is far more resource-efficient than launching a separate browser process per proxy.

• browser = await playwright.chromium.launch()
• context1 = await browser.new_context(proxy={"server": "http://gate.decodo.com:7000", "username": "user-session-1", "password": "pass"})
• context2 = await browser.new_context(proxy={"server": "http://gate.decodo.com:7000", "username": "user-session-2", "password": "pass"})
• Each context with a distinct session string in the username gets a different sticky IP from the gateway

Stealth patches

Out of the box, Playwright's Chromium exposes navigator.webdriver as true and several other automation-specific properties that basic anti-bot checks look for immediately, regardless of how good your proxy is. Community stealth patches address these by overriding the exposed properties to match a real browser's values.

Patchright, a maintained Playwright fork, applies these patches at a deeper level than JavaScript-only overlay patches, modifying behavior closer to the browser engine itself, which holds up better against detection systems that specifically test for the side effects of shallow JS patches rather than just checking the patched properties directly.

Even with stealth patches applied, a datacenter proxy paired with a stealth browser still fails against advanced anti-bot systems - the IP-layer signal and the browser-fingerprint signal are independent checks, and both need to be addressed for real success rates against DataDome or PerimeterX-protected sites.

Managed Scraping Browser alternative

Bright Data's Scraping Browser is a hosted, remote browser you connect to via the standard Playwright/Puppeteer CDP protocol, with proxy rotation, fingerprint management and CAPTCHA solving already handled server-side, meaning your local code just drives a remote browser rather than managing stealth patches and proxy configuration yourself.

This trades some cost and a small amount of extra latency (connecting to a remote browser rather than a local one) for significantly reduced engineering overhead and typically higher success rates against protected sites, since Bright Data continuously updates its bypass techniques as anti-bot systems evolve.

For teams without dedicated anti-detection engineering resources, starting with a managed scraping browser from Bright Data or a similar Decodo offering is usually faster to production than building and maintaining a DIY stealth stack.

Firefox and WebKit configuration

The same proxy configuration pattern works across all three Playwright browser engines - firefox.launch and webkit.launch accept the identical proxy object structure as chromium.launch, though fingerprint characteristics differ meaningfully between engines.

Camoufox, a hardened Firefox fork built specifically for anti-detection scraping, integrates with Playwright's automation protocol while patching Firefox at the engine level, and is worth evaluating as an alternative to Chromium-based stealth setups particularly against sites that specifically target Chromium automation fingerprints.

WebKit is used less frequently for scraping since its automation surface is less studied by the community, but it can occasionally succeed against sites whose anti-bot rules are tuned primarily against Chromium and Firefox signatures.

Handling proxy authentication errors

A 407 Proxy Authentication Required error in Playwright almost always means the username or password in your proxy configuration is incorrect, or your provider requires IP whitelisting instead of credential-based auth and your current IP is not on that whitelist.

Connection timeouts when using a proxy with Playwright can indicate the proxy server address or port is wrong, the exit IP is temporarily unavailable, or a firewall is blocking outbound traffic on the proxy's port - check the provider's status page and confirm the exact gateway hostname and port from your dashboard.

• 407 -> verify username/password or whitelist status in provider dashboard
• ERR_TUNNEL_CONNECTION_FAILED -> proxy server unreachable; check port and firewall rules
• ERR_PROXY_CONNECTION_FAILED -> confirm gateway hostname is current; providers occasionally rotate gateway addresses

Performance considerations

Running many browser contexts concurrently for parallel scraping is significantly more memory-efficient than launching many full browser instances, since contexts share the underlying browser process while maintaining isolated storage and proxy configuration - a single machine can typically run 20-50 concurrent contexts depending on target page complexity and available RAM.

For very high-volume scraping where full browser rendering is unnecessary, consider whether a lighter HTTP-based approach with curl_cffi (which mimics browser TLS fingerprints without rendering) could handle the target instead, reserving full Playwright browser automation for targets that specifically require JavaScript execution or complex interaction.

Common pitfalls

The most common pitfall is setting the proxy only at browser launch when the workload actually needs per-context rotation - this locks every context opened from that browser instance to the same IP, defeating the purpose of using multiple contexts for parallel work.

Another pitfall is assuming a residential proxy alone solves detection - without stealth patches, Playwright's default automation fingerprint gets flagged by any anti-bot system doing basic JavaScript-level checks, regardless of how clean the IP is.

Teams also commonly forget to close contexts after use, leading to memory leaks in long-running scraping processes; always call context.close() once a task using that context's proxy session is complete.

Verdict

For DIY Playwright scraping, configure proxies at the context level using a residential gateway from Bright Data or Decodo, layer on Patchright or Camoufox for engine-level stealth, and handle 407 and timeout errors with clear retry logic. For teams that would rather not maintain that stack, Bright Data's Scraping Browser provides a managed alternative that handles proxy rotation, fingerprinting and CAPTCHA solving server-side.

Frequently Asked Questions