The reliable way to configure a custom proxy is to set it at the scope your automation framework actually supports, provide the endpoint in the protocol format it expects, keep proxy credentials separate from website credentials, and verify traffic from the running browser. In Playwright, you can apply an HTTP(S) or SOCKSv5 proxy to the whole browser, a test run, or an individual browser context. Puppeteer uses Chromium launch arguments and page authentication, with important SOCKS5 limitations.
What a browser proxy configuration controls
A browser proxy routes page requests through a specified server instead of connecting directly to each destination. A useful configuration answers five questions:
- Scope: should every test share one route, or should each session use a different route?
- Protocol: is the endpoint HTTP, HTTPS, or SOCKSv5?
- Authentication: does the proxy require a username and password, and does the browser support that authentication mode?
- Bypass rules: which hosts must connect directly?
- Installation traffic: does downloading the automation browser need a separate proxy setting?
A proxy setting does not by itself guarantee anonymity, a particular geographic result, immunity from blocking, or permission to access a site. Confirm that your provider permits the intended use and test the endpoint in your own environment.
Playwright: configure a custom proxy
Playwright documents HTTP(S) and SOCKSv5 proxy support. Its proxy object accepts a server plus optional username, password, and a comma-separated bypass list. See the Playwright Network documentation and the BrowserType API reference for version-specific details.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Option 1: test-run configuration
Use use.proxy when all tests in a project should share the same route. In playwright.config.js:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
proxy: {
server: 'http://proxy.example:3128',
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
bypass: '.internal.example,localhost',
},
},
});Replace the hostname, port, and bypass values with those supplied by your proxy service. Store secrets in environment variables or your CI secret store, not in source control. Run a test normally; Playwright creates contexts using this proxy configuration.
Option 2: browser launch scope
Use chromium.launch({ proxy }) when the browser process should use one proxy for all contexts it creates:
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: {
server: 'http://proxy.example:3128',
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
bypass: '.internal.example,localhost',
},
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();This is convenient for a single route, but it is less flexible when sessions need different egress paths.
Recommended Free Tools
Rank #2
- Used Book in Good Condition
Option 3: per-context routing
Choose browser.newContext({ proxy }) when separate sessions need separate endpoints. A context isolates cookies, storage, and its proxy route:
import { chromium } from 'playwright';
const browser = await chromium.launch();
const usContext = await browser.newContext({
proxy: {
server: 'http://us-proxy.example:3128',
username: process.env.US_PROXY_USER,
password: process.env.US_PROXY_PASSWORD,
},
});
const euContext = await browser.newContext({
proxy: { server: 'socks5://eu-proxy.example:1080' },
});
await usContext.newPage().then(page => page.goto('https://example.com'));
await euContext.newPage().then(page => page.goto('https://example.com'));
await browser.close();Use the context level for multi-tenant tests or workflows that must select a route at runtime. The endpoint scheme must match the service: do not label an HTTP proxy as SOCKS or vice versa.
Proxy credentials are not website credentials
The proxy username and password authenticate the connection to the proxy. A destination site may separately require HTTP authentication, a form login, cookies, or an authorization header. Configure those independently. Supplying website credentials in the proxy fields can produce authentication failures or expose secrets to the wrong service.
Puppeteer configuration and its caveats
A current third-party Puppeteer guide describes passing a proxy through Chromium’s launch arguments and answering HTTP proxy challenges with page.authenticate():
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://proxy.example:3128'],
});
const page = await browser.newPage();
await page.authenticate({
username: process.env.PROXY_USER,
password: process.env.PROXY_PASSWORD,
});
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await browser.close();See Using Proxies with Puppeteer. That guide warns that Chrome’s SOCKS proxy implementation does not support SOCKS5 authentication and that one authentication pair can conflict when both the proxy and the destination website demand different credentials. Treat this as browser- and version-sensitive: validate the exact Puppeteer and Chrome versions you deploy. Do not assume Playwright’s proxy API can be copied to Puppeteer or Selenium.
Browser installation behind a proxy
Routing page traffic and downloading Playwright’s browser binaries are separate operations. A browser can successfully load pages through a proxy while installation fails because the archive downloader has no route.
- Set
HTTPS_PROXYfor the installation command, using the endpoint format accepted by your environment:HTTPS_PROXY=http://proxy.example:3128 npx playwright install chromium - If a corporate intercepting proxy replaces certificates and Playwright reports a certificate-chain error, provide the organization’s root CA with
NODE_EXTRA_CA_CERTSrather than disabling TLS verification:NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem npx playwright install chromium - For slow archive downloads, increase
PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT:PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT=120000 npx playwright install chromium
These installation variables are documented in Playwright Browsers. Keep the CA file protected and use the same environment in local setup and CI.
How to verify the route safely
- Confirm the proxy host resolves and the port is reachable from the machine running the browser.
- Run a minimal script against a controlled diagnostic endpoint or a service you are authorized to query.
- Check the response and server logs for the expected egress address; do not infer success merely because the page rendered.
- Test a bypass host and a proxied host separately. A bypass rule such as
localhostshould connect directly. - Repeat with the exact browser, framework, and container image used in production. Network policy, DNS, certificate stores, and IPv4/IPv6 behavior can differ between environments.
Common failures and fixes
Proxy server cannot be reached
Symptoms: connection refused, timeout, or DNS errors. Check the scheme, hostname, port, firewall egress rules, and whether the endpoint is reachable from the CI worker rather than your laptop.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
407 Proxy Authentication Required
Cause: missing or incorrect proxy credentials, or an authentication method unsupported by the browser. Confirm the pair with the provider, remove accidental whitespace, and test HTTP authentication before attempting SOCKS5 authentication.
Pages load directly instead of through the proxy
Cause: the proxy was configured at a scope that is not used by the page, or the destination matches the bypass list. Inspect the actual context creation code and temporarily remove bypass entries to isolate the issue.
TLS or certificate errors during installation
Cause: an intercepting proxy’s root certificate is absent. Set NODE_EXTRA_CA_CERTS to the approved CA bundle. Disabling certificate verification is not a safe shortcut.
SOCKS5 login fails in Puppeteer
Chrome’s SOCKS implementation may not support SOCKS5 authentication, according to the Puppeteer guide. Use an endpoint and authentication mode supported by your exact Chrome/Puppeteer combination, or ask the provider for an alternative endpoint.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Best Value
The proxy works locally but not in CI
Compare environment variables, secret injection, outbound firewall policy, DNS, container CA certificates, and clock settings. Log the selected host and port (never the password) and retain the framework’s network error.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choosing scope and options
| Decision | Use this approach | Important check |
|---|---|---|
| One route for every test | Playwright use.proxy |
All projects inherit the same endpoint. |
| One route for a browser process | chromium.launch({ proxy }) |
Contexts created by that process share the route. |
| Different routes per session | browser.newContext({ proxy }) |
Create each context with the intended endpoint. |
| HTTP(S) endpoint | Use the provider’s HTTP URL | Check proxy authentication requirements. |
| SOCKSv5 endpoint | Use the provider’s SOCKS URL | Verify authentication support in your framework/browser. |
| Direct internal services | Set a comma-separated bypass list |
Include only hosts that should avoid the proxy. |
Performance, reliability, and cost considerations
Proxy latency, bandwidth limits, connection reuse, geographic routing, and provider availability affect run time, but the cited framework documentation does not establish universal speed or success rates. Measure your own workflow with the same URLs, concurrency, retries, and CI region you will use in production. Keep retries bounded: repeated attempts can multiply traffic and costs at the proxy provider or target service. Cache browser binaries in CI where policy permits, while still testing installation with the required proxy and CA variables on clean workers.
Or skip the browser setup
If your goal is a clean website image rather than interactive browser control, ScreenshotNeo provides a single screenshot API request. Before capture it accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf.
Read the ScreenshotNeo API documentation for proxy and capture options. A one-call example:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe same request in Python:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)And Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Every plan includes the features. The Free plan provides 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Can I use different proxies for different Playwright pages?
Configure separate browser contexts with browser.newContext({ proxy: ... }); pages inside a context share that context’s route.
Does setting HTTPS_PROXY configure page traffic in Playwright?
No. Playwright’s HTTPS_PROXY installation setting is for downloading browser binaries. Configure page traffic with the framework’s proxy option.
Should proxy credentials be the same as website credentials?
No. They authenticate different services and should be stored and supplied separately.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
