Puppeteer Proxy Setup: --proxy-server, Authentication and Per-Context Proxies

Set the proxy when you launch the browser

The Puppeteer documentation says the args option of puppeteer.launch() passes additional command-line arguments to the browser. The argument for a proxy is Chromium's --proxy-server, which the Chromium proxy documentation describes. Its value is a proxy address; with a http:// prefix Chrome uses an HTTP proxy.

Set the proxy when you launch the browser: example

import puppeteer from 'puppeteer'

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://proxy-host:port'],
})
const page = await browser.newPage()
await page.goto('https://ipinfo.io/json')
console.log(await page.evaluate(() => document.body.innerText))
await browser.close()

Replace proxy-host and port with the values from your proxy list. Give the username and password to page.authenticate as shown next.

• Sources:
• Puppeteer API: LaunchOptions, args
• Chromium documentation: Proxy support in Chrome

Username and password with page.authenticate

Puppeteer's documentation describes Page.authenticate() as providing credentials for HTTP authentication, and says passing null disables it. It also notes that request interception is turned on behind the scenes to implement authentication, which might affect performance. Call it before the first navigation of the page.

Username and password with page.authenticate: example

const page = await browser.newPage()
await page.authenticate({ username: 'USERNAME', password: 'PASSWORD' })
await page.goto('https://ipinfo.io/json')

The credentials are separate fields, so the password needs no URL encoding here.

Username and password with page.authenticate, continued

The Chromium documentation says HTTP proxies in Chrome support the same authentication schemes as target servers: Basic, Digest, Negotiate and NTLM. A proxy that rejects the login answers 407; see the authentication required guide.

• authentication required guide

• Sources:
• Puppeteer API: Page.authenticate()
• Chromium documentation: Proxy support in Chrome

One proxy per browser context

The Puppeteer API reference lists proxyServer in the options of a browser context: a proxy server with an optional port to use for all requests, with the username and password set in Page.authenticate. A second option in that list takes the hosts that should not use the proxy. This lets two contexts in one browser use two different proxies.

One proxy per browser context: example

const context = await browser.createBrowserContext({
  proxyServer: 'http://proxy-host:port',
})
const page = await context.newPage()
await page.authenticate({ username: 'USERNAME', password: 'PASSWORD' })
await page.goto('https://ipinfo.io/json')
await context.close()

Create the page from the context, not from the browser, so it uses the context proxy.

• Sources:
• Puppeteer API: BrowserContextOptions
• Puppeteer API: Browser.createBrowserContext()

HTTP or SOCKS5

The Chromium proxy documentation lists HTTP, HTTPS, SOCKS4 and SOCKS5 proxy schemes. For SOCKS5 it says Chrome does name resolution on the proxy side and that no authentication methods are supported for SOCKS5 in Chrome. In practice, a SOCKS5 proxy that needs a username and password cannot be used with Chrome through this setting. Choose an HTTP proxy for Puppeteer when the proxy has a login. If you need SOCKS5 for another program, see the SOCKS5 proxies page.

• SOCKS5 proxies page

• Sources:
• Chromium documentation: Proxy support in Chrome

Check the exit

Open https://ipinfo.io/json as in the examples and read the country and org fields; the proxy location guide explains how. If the response shows your own address, the proxy was not applied: make sure the argument is in the launch call, or that the page was created from the context that has proxyServer.

• proxy location guide

Common errors

The Chromium documentation says that when the proxy server is unreachable, requests fail with ERR_PROXY_CONNECTION_FAILED. Check the host, the port and the scheme, and use the connection failed guide for a full list. A 407 or a login loop means the credentials were not given to page.authenticate, or are wrong; copy them again. To run the same job in another browser tool, the Playwright page covers its proxy setting, and the Node.js proxy guide covers plain HTTP clients. Make sure that any automation you run follows the terms of the sites you visit.

• connection failed guide
• Playwright page
• Node.js proxy guide

• Sources:
• Chromium documentation: Proxy support in Chrome

How to do it with Proxy302

Any of these setups only needs the host, port, username and password of a Proxy302 proxy. For Puppeteer, choose HTTP, which is on port 2222 of proxy.proxy302.com. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy. A static ISP IP stays fixed for the whole lease term and does not rotate. The table shows exits in 7 countries from our latest hourly check; the probe sends its request to ChatGPT, which is only an example target. Details are on the rotating residential page and in the proxy location guide.

• rotating residential page
• proxy location guide

Measured exits: ChatGPT from 7 countries

Hourly check of the Proxy302 probe, 28 October 2026, 14:56 UTC: one request to ChatGPT per country through a dynamic residential exit, using the public Proxy302 entry. Only the first three octets of an IP are public. One sample per country, not an average; later checks will differ.

• Sources:
• Proxy302 hourly connectivity check

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, and keep Protocol on HTTP or choose SOCKS5, then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Enter the details in the browser or tool you are setting up.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. There is no free trial, and the smallest purchase is 1 GB. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

Proxy address, port, username and password

Every working proxy is described by five basic fields: protocol, host address, port, login, and password.

407 Proxy Authentication Required

HTTP 407 Proxy Authentication Required comes from the proxy server, not from the website you are trying to reach.

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.

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.

Playwright proxies

Playwright proxy setup with username and password: static datacenter IPs for tests and CI, rotating residential from US$1.50/GB when a site blocks servers.

View options and pricing

Node.js proxy setup

Ways to use an HTTP or SOCKS5 proxy in Node.js, with short examples and an exit check.