Puppeteer Rotate Proxies: Per Page, Context or Browser

Three ways to rotate

Based on the Puppeteer API pages and the proxy-chain README, read 13 November 2026, and the Proxy302 product facts.

• Sources:
• Puppeteer API: BrowserContextOptions
• proxy-chain README (apify/proxy-chain)
• Proxy302 product facts and price list

Why there is no per-page proxy

The Puppeteer reference lists proxyServer as an option of a browser context: the proxy for all requests of that context. The launch argument applies to the whole browser. A page cannot be moved to another proxy once it is open, so the smallest unit you can rotate is the context.

Page.authenticate gives the credentials. Puppeteer notes that it turns request interception on behind the scenes, which might affect performance, so call it on the pages that need it and before the first navigation.

• Sources:
• Puppeteer API: BrowserContextOptions
• Puppeteer API: Page.authenticate

A context per proxy

import puppeteer from 'puppeteer'

const proxies = [
  { server: 'http://HOST1:2222', username: 'LOGIN1', password: 'PASSWORD1' },
  { server: 'http://HOST2:2222', username: 'LOGIN2', password: 'PASSWORD2' },
]

const browser = await puppeteer.launch()
for (const p of proxies) {
  const context = await browser.createBrowserContext({ proxyServer: p.server })
  const page = await context.newPage()
  await page.authenticate({ username: p.username, password: p.password })
  await page.goto('https://ipinfo.io/json')
  console.log(await page.evaluate(() => document.body.innerText))
  await context.close()
}
await browser.close()

Example only. Replace HOST, LOGIN and PASSWORD with the values from My assets. Each run prints the IP details for that proxy.

A browser per proxy, with proxy-chain

When you want a whole browser per proxy, the launch flag takes a URL but Chrome does not take the username and password from it. The proxy-chain library starts a small local proxy that holds the login and returns a local URL to use in --proxy-server; you close it when the browser is done.

Chrome supports no authentication methods for SOCKS5, so give the browser an HTTP address.

• Sources:
• proxy-chain README (apify/proxy-chain)
• Chromium notes on proxy settings

A browser per proxy

import puppeteer from 'puppeteer'
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain'

const localUrl = await anonymizeProxy('http://LOGIN:PASSWORD@HOST:2222')
const browser = await puppeteer.launch({ args: [`--proxy-server=${localUrl}`] })
const page = await browser.newPage()
await page.goto('https://ipinfo.io/json')
console.log(await page.evaluate(() => document.body.innerText))
await browser.close()
await closeAnonymizedProxy(localUrl, true)

Example only. Needs npm install puppeteer proxy-chain. Replace HOST, LOGIN and PASSWORD.

One rotating gateway

With rotating residential traffic you set one proxy, proxy.proxy302.com on HTTP port 2222, and the exit IP changes by itself. Without a session, every new connection gets a new IP, while a connection that is reused keeps its IP. A page opens several connections, so different requests of one page can leave from different IPs.

If a page must keep one IP, generate the proxy with a session; on the Budget line the console offers 10, 30, 60 or 120 minutes, or your own number of minutes from 1 to 120. For a fixed address for days, use a static IP instead. The Budget line costs US$1.50 per GB.

• Rotating residential proxies

• Sources:
• Proxy302 product facts and price list

One browser, one gateway

import puppeteer from 'puppeteer'

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://proxy.proxy302.com:2222'],
})
for (let i = 0; i < 3; i++) {
  const page = await browser.newPage()
  await page.authenticate({ username: 'LOGIN', password: 'PASSWORD' })
  await page.goto('https://ipinfo.io/json')
  console.log(await page.evaluate(() => document.body.innerText))
  await page.close()
}
await browser.close()

Example only. Replace LOGIN and PASSWORD with the values from My assets. If two pages print the same IP, a connection was reused: use a new context or browser for the next job.

Choose and test in 4 steps

1. Step 1

   Decide what must stay together. A login flow needs one IP for its whole run: use a context or browser per proxy, or a session. Independent page fetches can use the gateway.

2. Step 2

   Copy host, port, username and password from My assets and use the HTTP protocol, because Chrome has no SOCKS5 login.

   • Puppeteer proxy setup

3. Step 3

   Run one of the code examples with two proxies or two runs and compare the ip field of ipinfo.io/json.

   Expected result Different IPs for different contexts or runs, and the same IP inside one session.

4. Step 4

   Only then add your real task. Respect the terms of the sites you visit and keep the request rate reasonable.

When rotation does not work

FAQ

Further reading

Puppeteer proxy setup

Set an HTTP proxy in Puppeteer with --proxy-server, page.authenticate and browser contexts, and check the exit IP.

Puppeteer proxy setup

Point Puppeteer at proxy.proxy302.com with --proxy-server, authenticate with page.authenticate() on HTTP port 2222, get a new exit IP on each new connection or hold a sticky session; SOCKS5 on 3333 serves tools outside the browser.

Fix ERR_PROXY_CONNECTION_FAILED

The ERR_PROXY_CONNECTION_FAILED error appears in Chrome and Edge when the browser cannot establish a connection with a proxy server.

Rotating residential proxies

Real household IPs in 195+ countries; the Premium line adds state and major-city targeting. A new IP on every new connection, or keep sticky sessions. From US$1.50/GB, US$1.35/GB at 100 GB. HTTP and SOCKS5.

View options and pricing