How do I use residential proxies with Puppeteer?

To use a residential proxy with Puppeteer, you typically pass the proxy server when launching Chromium, then handle proxy authentication if required.

Basic example

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    headless: true,
    args: [
      '--proxy-server=http://proxy-host:proxy-port'
    ]
  });

  const page = await browser.newPage();

  // If your proxy needs username/password:
  await page.authenticate({
    username: 'proxy-username',
    password: 'proxy-password'
  });

  await page.goto('https://example.com', { waitUntil: 'networkidle2' });

  console.log(await page.title());

  await browser.close();
})();

Notes

1) Proxy format

• HTTP proxy:

  --proxy-server=http://host:port
  

• SOCKS5 proxy:

  --proxy-server=socks5://host:port
  

2) Authentication

If your residential proxy provider gives you credentials, use:

await page.authenticate({ username, password });

3) Per-page proxy

Puppeteer doesn’t support different proxies per page in the same browser instance out of the box. Common approaches are:

• launch separate browser instances
• use browser contexts with tools/libraries that support proxy routing
• use a proxy rotation service upstream

4) Example with environment variables

const proxy = 'http://user:pass@proxy-host:proxy-port';

const browser = await puppeteer.launch({
  args: [`--proxy-server=${proxy}`]
});

Note: even if credentials are embedded in the proxy URL, Puppeteer/Chromium may still require page.authenticate() for some proxies.

Troubleshooting

• Proxy not working: verify the proxy protocol matches the provider’s requirements.
• Auth failed: make sure you call page.authenticate() before page.goto().
• IP still unchanged: some providers require session parameters or specific gateway domains.
• CAPTCHAs / blocks: residential proxies help, but don’t eliminate anti-bot detection.

If you want, I can also show:

1. a rotating residential proxy setup, or
2. a working Puppeteer script with Bright Data / Oxylabs / Smartproxy-style proxies.