Guide
How to Use a Proxy with Playwright and Puppeteer: Correct Setup for Browser Automation
In Playwright, a proxy is set with the proxy object in the launch or newContext call; in Puppeteer, with --proxy-server or createBrowserContext plus page.authenticate. A separate IP per context, the SOCKS5 authentication limit, sticky sessions, saving traffic and an error table.
Key takeaways
- In Playwright, the proxy is passed to chromium.launch() or browser.newContext() as a proxy: { server, username, password } object; the password sits in its own field, so it needs no percent-encoding.
- In Puppeteer, the proxy address is set with the --proxy-server argument or createBrowserContext({ proxyServer }); the username and password are entered on every page with page.authenticate() before page.goto().
- Chromium doesn’t support SOCKS5 proxies with a username and password: Playwright fails to launch, and Puppeteer returns ERR_NO_SUPPORTED_PROXIES. The fix is the plan’s HTTP address or a local bridge with proxy-chain.
- Puppeteer doesn’t throw on a wrong proxy password; page.goto() returns a response with status 407, so you should check the response’s status() value.
- For sticky sessions, opening a separate context for each session ID keeps cookies and the exit IP together in one unit; on plans billed per GB, blocking images cuts traffic.
In Playwright, you set a proxy with a proxy: { server, username, password } object passed to chromium.launch() or browser.newContext(). In Puppeteer, the address goes to Chrome through the --proxy-server argument or through createBrowserContext({ proxyServer }), and the username and password are entered with page.authenticate(). Neither tool’s Chromium supports a SOCKS5 proxy with a username and password; in that case you use the plan’s HTTP address or a local bridge.
Proxy settings in browser automation work differently from HTTP clients such as requests or fetch. Every image, script and API call the page loads goes out through the same proxy, and the browser itself handles authentication. The examples use the WeProxy gateway address gw.weproxy.com.tr:8989; USER and PASSWORD are the credentials from your dashboard. All examples were run against a local test proxy with Playwright 1.65, Puppeteer 25 and Chrome 158.
How do you write a proxy address in Playwright and Puppeteer?
Both tools expect the proxy server in scheme://host:port form. Even when the target site is HTTPS, an HTTP proxy address starts with http://: the browser sends a CONNECT request to the proxy and sets up the TLS connection inside that tunnel. If you write gw.weproxy.com.tr:8989 without a scheme, Playwright treats it as an HTTP proxy.
Don’t put the username and password inside the address. Playwright takes them in separate fields of the proxy object, and Puppeteer takes them through page.authenticate(). That’s why a password containing @ or : needs no percent-encoding; on the test proxy, the password p@ss:word worked unencoded in both tools. A password typed on the command line also shows up in the system’s process list.
Keep credentials in environment variables instead of hardcoding them:
export WEPROXY_USERNAME="USER"
export WEPROXY_PASSWORD="PASSWORD"
If the dashboard gave you a list in ip:port:user:pass format, the proxy format converter helps you split the lines. The formats are covered in detail in the proxy formats guide.
How do you use a proxy in Playwright?
The shortest route is to pass the proxy when you launch the browser. Every context and page opened from that browser then goes out through the same proxy:
import { chromium } from 'playwright';
const browser = await chromium.launch({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const page = await browser.newPage();
await page.goto('https://api.ipify.org?format=json');
console.log(await page.textContent('body')); // {"ip":"<proxy exit IP>"}
await browser.close();
The Python version takes the same fields as a dictionary:
import os
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(proxy={
"server": "http://gw.weproxy.com.tr:8989",
"username": os.environ["WEPROXY_USERNAME"],
"password": os.environ["WEPROXY_PASSWORD"],
})
page = browser.new_page()
page.goto("https://api.ipify.org?format=json")
print(page.text_content("body"))
browser.close()
If some addresses shouldn’t go through the proxy, list the domains, separated by commas, in the bypass field, for example bypass: 'localhost, .internal.example', which is handy for local services in a test environment. If you need to send requests outside the browser in Python, see the requests and httpx examples in how to use a proxy in Python.
How do you set a separate proxy for each context in Playwright?
In Playwright, a context is a separate browser profile with its own cookies and storage. If you pass the proxy to browser.newContext(), a single browser process can use more than one exit IP:
import { chromium } from 'playwright';
const browser = await chromium.launch();
const proxied = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
},
});
const direct = await browser.newContext();
const p1 = await proxied.newPage();
const p2 = await direct.newPage();
await p1.goto('https://api.ipify.org');
await p2.goto('https://api.ipify.org');
console.log(await p1.textContent('body'), await p2.textContent('body'));
await browser.close();
In testing, every request from the proxied context went through the proxy, and the second context connected directly. Older Playwright versions on Windows needed a placeholder proxy in the launch call for context proxies to work; Playwright 1.65 no longer does. The proxy given to a context is also used for API requests sent with context.request, so you don’t need a separate HTTP client to query a JSON endpoint without opening a page.
How do you use a proxy with a username and password in Puppeteer?
Puppeteer takes the proxy through Chrome’s --proxy-server argument. You pass credentials on each page with page.authenticate(), and that call has to come before page.goto():
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
args: ['--proxy-server=http://gw.weproxy.com.tr:8989'],
});
try {
const page = await browser.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
const res = await page.goto('https://api.ipify.org?format=json');
if (res.status() === 407) throw new Error('Proxy credentials rejected');
console.log(await page.evaluate(() => document.body.innerText));
} finally {
await browser.close();
}
In testing, page.goto() with a wrong password didn’t throw. It returned a response with status 407, so a script without the status() check can save the proxy’s error page as if it were data. According to the Puppeteer documentation, page.authenticate() turns on request interception behind the scenes, which adds a small speed cost across many pages.
On plans where the proxy works with an IP whitelist, you don’t need page.authenticate(); the exit IP of the machine running the code has to be registered in the dashboard. A table of which method applies to which product is in the proxy authentication guide. A short version of the setup steps is on the Puppeteer integration page.
How do you set a different proxy per context in Puppeteer?
--proxy-server applies to the whole browser. In current Puppeteer versions, browser.createBrowserContext() accepts the proxyServer and proxyBypassList options, so each context in a single Chrome process can use a different proxy:
const browser = await puppeteer.launch();
const ctx = await browser.createBrowserContext({
proxyServer: 'http://gw.weproxy.com.tr:8989',
proxyBypassList: ['localhost'],
});
const page = await ctx.newPage();
await page.authenticate({
username: process.env.WEPROXY_USERNAME,
password: process.env.WEPROXY_PASSWORD,
});
await page.goto('https://api.ipify.org');
Credentials are set per page, not per context, so repeat the page.authenticate() call on every new page you open in the context. If your older Puppeteer version lacks this option, you have to start a separate puppeteer.launch() process for each proxy.
How do you use a SOCKS5 proxy in browser automation?
Chromium doesn’t support username and password authentication on SOCKS5 proxies. Playwright won’t even start the browser in that case and fails with Browser does not support socks5 proxy authentication. In Puppeteer, if you write the credentials as --proxy-server=socks5://user:pass@host:port, the page fails to open with net::ERR_NO_SUPPORTED_PROXIES. A SOCKS5 proxy without authentication works fine in both tools.
If your plan also offers HTTP, use the HTTP address in the browser; SOCKS5 has no advantage for page traffic. If SOCKS5 is a must, open a local HTTP bridge without authentication on the machine. The proxy-chain package does this in a single line:
import puppeteer from 'puppeteer';
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain';
const user = encodeURIComponent(process.env.WEPROXY_USERNAME);
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);
const local = await anonymizeProxy(`socks5://${user}:${pass}@gw.weproxy.com.tr:8989`);
// local: http://127.0.0.1:<port>
const browser = await puppeteer.launch({ args: [`--proxy-server=${local}`] });
const page = await browser.newPage();
await page.goto('https://api.ipify.org');
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();
await closeAnonymizedProxy(local, true);
The bridge address is a URL, so here you encode the password with encodeURIComponent. The local bridge listens only on 127.0.0.1, and you can use the same approach in Playwright as server: local. The HTTP vs SOCKS5 article explains how the two protocols differ. The real-SIM Mobile 5G Proxy works over HTTP only, so that product doesn’t need a bridge.
How do Playwright and Puppeteer proxy settings compare?
| Feature | Playwright | Puppeteer |
|---|---|---|
| Browser-wide proxy | launch({ proxy: { server } }) | args: ['--proxy-server=...'] |
| Proxy per context | newContext({ proxy }) | createBrowserContext({ proxyServer }) |
| Username and password | proxy.username, proxy.password | page.authenticate() on every page |
| Addresses that skip the proxy | bypass: 'a.com, .b.com' | proxyBypassList or --proxy-bypass-list |
| SOCKS5 with authentication | Not supported, launch error | Not supported, ERR_NO_SUPPORTED_PROXIES |
| Behavior on a wrong password | page.goto() throws | page.goto() returns a 407 response |
| Language support | JavaScript, Python, Java, .NET | JavaScript |
In Playwright, credentials are part of the proxy setting, so code for multi-context jobs stays shorter. If your project is already built on Puppeteer, there’s no need to switch tools; createBrowserContext gives you the same flexibility.
Which proxy type suits browser automation?
A browser produces far more traffic than an HTTP client. A single product page with its images, fonts and scripts can weigh several megabytes. So the product choice depends on both the target and the billing model:
| Job | Suitable product | Why |
|---|---|---|
| Multi-page scraping, SERP and price checks | Rotating Residential IPv4 | Sticky and rotating sessions, country and city targeting, HTTP and SOCKS5 |
| High-volume, unprotected targets | Rotating Datacenter IPv4 | Pay per GB, 1–5 minute sticky sessions |
| Long logged-in sessions, a fixed IP per account | ISP Proxy or Static Residential IPv4 | The IP stays the same for the whole period; no traffic limit on Static Residential |
| Mobile view and app testing | Mobile 5G Proxy | Real SIM, HTTP only, username/password |
On plans billed per GB, blocking images and media cuts traffic noticeably. In Playwright, a context-level route is enough:
await context.route('**/*', (route) => {
const type = route.request().resourceType();
return ['image', 'media', 'font'].includes(type) ? route.abort() : route.continue();
});
Jobs like reading prices or stock don’t need the page to render visually; the text and JSON-LD data are usually enough. How to set up price monitoring during sale periods is covered in the Black Friday price tracking guide. IP type and session choices for scraping jobs are also explained on the web scraping page.
How do you match sticky sessions to browser contexts?
On a rotating gateway, the proxy address stays the same while the exit IP changes from the pool. Logins, shopping carts and multi-step forms, though, need every step to go out from the same IP. In WeProxy residential pools, you get this by adding a session ID to the username. Take the username format and session duration for your product from the dashboard.
In browser automation, the cleanest match is a separate context for each session. Cookies, storage and the exit IP then stay together in one unit:
import { chromium } from 'playwright';
// Usernames are copied from the dashboard; each profile carries its own session ID.
const PROFILES = ['USER_WITH_SESSION_1', 'USER_WITH_SESSION_2'];
const browser = await chromium.launch();
for (const username of PROFILES) {
const context = await browser.newContext({
proxy: {
server: 'http://gw.weproxy.com.tr:8989',
username,
password: process.env.WEPROXY_PASSWORD,
},
locale: 'en-US',
timezoneId: 'America/New_York',
});
const page = await context.newPage();
await page.goto('https://api.ipify.org');
console.log(username, await page.textContent('body'));
await context.close();
}
await browser.close();
locale and timezoneId make the site show a language and date format that fit the proxy’s country, so a page opened from a US IP doesn’t come up with a foreign date format or a different currency. Two contexts shouldn’t share the same session ID. The sticky vs rotating guide has a scenario table showing which jobs need sticky and which need rotating. The same matching settings for antidetect browsers are in the antidetect browser + proxy article.
How do you verify the proxy is working, and what do the errors mean?
The quickest test is to open two contexts in the same browser, one with the proxy and one without, and compare their api.ipify.org results. If the two values match, the proxy setting isn’t reaching the browser. The My IP tool shows the exit IP’s country and network. To test the proxy independently of your code, use the proxy checker; a proxy that works there but not in the browser points to a problem in the script’s settings.
Errors captured on the test proxy with Chrome 158:
| Situation | Playwright | Puppeteer |
|---|---|---|
| No credentials given | net::ERR_INVALID_AUTH_CREDENTIALS | net::ERR_INVALID_AUTH_CREDENTIALS |
| Wrong password | net::ERR_HTTP_RESPONSE_CODE_FAILURE | No error, response status 407 |
| Couldn’t connect to the proxy | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
HTTP proxy written with https:// | net::ERR_PROXY_CONNECTION_FAILED | net::ERR_PROXY_CONNECTION_FAILED |
| SOCKS5 with authentication | Browser does not support socks5 proxy authentication | net::ERR_NO_SUPPORTED_PROXIES |
Retrying won’t change the result of a credentials error; first check that your plan is active and that the username matches the dashboard. If ERR_PROXY_CONNECTION_FAILED keeps coming back, your network or cloud provider may be blocking outbound traffic on port 8989. When the proxy connection works but the target returns codes such as 403 or 429, the proxy error codes guide explains which layer they come from. For these codes, retries with growing intervals and lower concurrency are usually enough.
How do you keep browser automation with a proxy compliant and secure?
If you’re writing automation that collects data, follow the target’s robots.txt file (RFC 9309) and terms of use even though the requests go out through a proxy, and keep the number of concurrent contexts at a level the site can handle. If you process personal data, obligations under KVKK (Turkey) and GDPR apply regardless of the proxy. Permitted and prohibited uses of WeProxy services are listed on the acceptable use page.
Screenshots and trace files contain page content and sometimes session cookies, so check them before sharing. Don’t print the proxy password in logs or error messages. For requests outside the browser, the undici and axios examples in how to use a proxy in Node.js work with the same proxy credentials as Playwright. The full API options are in the Playwright proxy documentation and the Puppeteer BrowserContextOptions documentation.
Frequently asked questions
How do I set up a proxy with a username and password in Playwright?
Pass a proxy object to chromium.launch() or browser.newContext(): put the http://host:port address in the server field and your dashboard credentials in the username and password fields. The credentials aren’t part of the address, so a password containing @ or : needs no encoding. In Python, the same fields go into the p.chromium.launch(proxy={...}) dictionary. Every context and page opened from that browser goes out through the same proxy.
How does proxy authentication work in Puppeteer?
Launch the browser with the --proxy-server=http://host:port argument, and on every new page call page.authenticate({ username, password }) before page.goto(). Don’t add the credentials to the --proxy-server address; Chromium doesn’t support that form, and the password shows up in the process list. On a wrong password, Puppeteer doesn’t throw but returns a response with status 407, so check the status() value of the page.goto() result.
Can different pages in one browser use different proxies?
Yes, at the context level. In Playwright, you pass a separate proxy object to each browser.newContext() call. In current Puppeteer versions, browser.createBrowserContext({ proxyServer }) does the same job, and credentials are still entered with page.authenticate(). Pages inside the same context share the same proxy; for a separate proxy per page, open a separate context for each page.
Why does Playwright show the “Browser does not support socks5 proxy authentication” error?
Chromium doesn’t support username and password authentication on SOCKS5 proxies, and Playwright catches this before launching the browser. If your plan also offers HTTP, use the HTTP address in the browser. If SOCKS5 is a must, use the anonymizeProxy function from the proxy-chain package to open an HTTP bridge without authentication on 127.0.0.1, then give that address to the browser.
How can I reduce proxy traffic in browser automation?
Images, fonts and videos make up most of the traffic. In Playwright, abort requests of the image, media and font types with context.route(); in Puppeteer, you do the same with page.setRequestInterception(true). Jobs that read prices, stock or text don’t need the page to render visually. On rotating plans billed per GB, this setting cuts consumption noticeably.









