Puppeteer proxy: --proxy-server, page.authenticate and a proxy per browser context
In this article
- 01 How do you set a proxy in Puppeteer?
- 02 Basic example
- 03 page.authenticate on every page
- 04 A different proxy per browser context
- 05 SOCKS5 and Puppeteer
- 06 Time zone and language
- 07 Rotating the IP between sessions
- 08 Common errors
- 09 Puppeteer with 65Proxy's Singapore 4G proxies
- 10 Frequently asked questions
Puppeteer sets a proxy in two parts: the address goes into Chrome's --proxy-server launch flag, and the username and password go into page.authenticate() on each page. For a different proxy per session, use browser.createBrowserContext({ proxyServer }). Chrome can't use SOCKS5 with a password, so use the proxy's HTTP port. Every example below was tested on 18 November 2026 with Puppeteer 25.18 and Chrome 157.
How do you set a proxy in Puppeteer?
| Part | Where it goes | Example |
|---|---|---|
| Proxy address and port | --proxy-server in launch({ args }) |
--proxy-server=http://HOST:PORT |
| Username and password | page.authenticate() on each page |
{ username: "USER", password: "PASS" } |
| Proxy per session | browser.createBrowserContext() |
{ proxyServer: "http://HOST:PORT" } |
Don't write the login into the flag as --proxy-server=http://USER:PASS@HOST:PORT: Chrome doesn't use credentials in its proxy settings, and pages fail to load.
Basic example
Install with npm install puppeteer, which also downloads a matching Chrome. Save the file as proxy.mjs and run node proxy.mjs:
import puppeteer from "puppeteer";
const browser = await puppeteer.launch({
args: ["--proxy-server=http://HOST:PORT"],
});
const page = await browser.newPage();
await page.authenticate({
username: process.env.PROXY_USER,
password: process.env.PROXY_PASS,
});
const res = await page.goto("https://65proxy.com/ip.json");
if (res.status() === 407) throw new Error("Wrong proxy username or password");
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();The page prints the IP the site sees and its country (SG for a Singapore proxy). If you drive a Chrome that's already installed, use puppeteer-core and pass its executablePath; the proxy code stays the same.
page.authenticate on every page
page.authenticate() belongs to one page. Call it on every page you create, before goto():
- Forget it and the page fails with
net::ERR_INVALID_AUTH_CREDENTIALS. - Give a wrong password and
goto()doesn't throw: it returns a response with status 407. That's why the example checksres.status(). - Performance: Puppeteer's documentation notes that
page.authenticate()turns on request interception behind the scenes, which can slow pages a little.
Chrome sometimes reuses a login it already has for other pages, but don't rely on that: a page that skips authenticate() may fail later.
A different proxy per browser context
A browser context is a separate session with its own cookies. Since Puppeteer 22, browser.createBrowserContext() takes a proxyServer, so one browser can run several proxies:
import puppeteer from "puppeteer";
const proxies = [
{ server: "http://HOST1:PORT1", username: process.env.USER1, password: process.env.PASS1 },
{ server: "http://HOST2:PORT2", username: process.env.USER2, password: process.env.PASS2 },
];
const browser = await puppeteer.launch();
for (const proxy of proxies) {
const context = await browser.createBrowserContext({ proxyServer: proxy.server });
const page = await context.newPage();
await page.authenticate({ username: proxy.username, password: proxy.password });
await page.goto("https://65proxy.com/ip.json");
console.log(await page.evaluate(() => document.body.innerText));
await context.close();
}
await browser.close();Older code calls this createIncognitoBrowserContext; it was renamed in Puppeteer 22. The option proxyBypassList takes a list of sites that skip the proxy. How many proxies you need for parallel sessions is in how many proxies do you need.
SOCKS5 and Puppeteer
Chrome supports SOCKS5 proxies only without a password, and page.authenticate() can't help: SOCKS5 has no login prompt for it to answer. Use the HTTP port of the same proxy. It reaches the same IP, and HTTPS sites still travel through an encrypted tunnel. More in SOCKS5 vs HTTP proxies.
Time zone and language
A Singapore IP with a browser on another country's time zone is an easy mismatch to spot. Set both per page:
await page.emulateTimezone("Asia/Singapore");
await page.setExtraHTTPHeaders({ "Accept-Language": "en-SG,en;q=0.9" });Then open our IP checker in that page to compare. The full list of checks is in how to check a proxy.
A proxy changes the IP, not the fact that a script drives the browser. Keep a reasonable pace and respect each site's terms; proxies for bots and automation covers where the line is.
Rotating the IP between sessions
Chrome keeps its connections to the proxy open, so rotating while pages load breaks them. Close the context, call the rotation link, wait for the new IP, then open a new context and call page.authenticate() again. The code that waits for the new IP is in rotating the IP with an API. Each 65Proxy proxy rotates at most once every 5 minutes.
Common errors
| Error | Cause | Fix |
|---|---|---|
net::ERR_INVALID_AUTH_CREDENTIALS |
No page.authenticate() on this page, or it ran after goto() |
Call it first, on every page |
Response status 407 |
Wrong username or password | Copy the login again; see 407 errors |
net::ERR_PROXY_CONNECTION_FAILED |
Wrong host or port, or the proxy can't be reached | Check the address; see can't reach the proxy |
net::ERR_TUNNEL_CONNECTION_FAILED on one site |
The proxy can't reach that site, for example an IPv6-only address | See tunnel errors |
Navigation timeout of 30000 ms exceeded now and then |
A slow moment or short drop on the 4G line | Raise the timeout and retry; see proxy keeps disconnecting |
If the proxy works in curl but not in Puppeteer, the problem is in the Puppeteer settings, most often a page without authenticate().
Puppeteer with 65Proxy's Singapore 4G proxies
Every 65Proxy proxy has an HTTP port for Puppeteer and a SOCKS5 port, one username and password, a rotation link, and a Singapore IP from the Singtel or M1 4G network. It is not shared with other customers.
- Plans: 1 day $4, 7 days $13, 1 month $32, plus monthly plans with more bandwidth (500GB $40, 1TB $65).
- Test your script first on the free 1-hour trial.
- Buy: get a Singapore 4G proxy for Puppeteer; it is delivered automatically once paid.
A browser downloads images, fonts and scripts, so it uses much more bandwidth than plain requests. If you don't need a browser, the HTTP clients in using a proxy in Node.js are lighter.
Frequently asked questions
Can I put the username and password in --proxy-server?
No. Chrome doesn't use credentials written into its proxy settings. Pass the address in --proxy-server and the login through page.authenticate().
Does Puppeteer support SOCKS5 with a password?
No, because Chrome doesn't. Use the HTTP port of the same proxy.
Can each page use a different proxy?
Each browser context can, with createBrowserContext({ proxyServer }). Pages inside one context share its proxy.
Should I use Playwright instead?
If you're starting fresh, Playwright's single proxy option (address, username and password together) is simpler. See Playwright proxy setup.