How to use a proxy with Puppeteer

Setup guide · Last revised Oct 20, 2026

The working script

const puppeteer = require("puppeteer");

(async () => {
  const browser = await puppeteer.launch({
    args: ["--proxy-server=http://proxy.example.com:8000"],
  });
  const page = await browser.newPage();
  await page.authenticate({ username: process.env.PROXY_USER, password: process.env.PROXY_PASS });
  const response = await page.goto("https://api.ipify.org");
  console.log(response.status(), await page.evaluate(() => document.body.innerText));
  await browser.close();
})();

200 203.0.113.24

--proxy-server is Chrome’s own setting: --proxy-server="foopy:8080" “will use the proxy at foopy:8080 for all traffic” (Chromium, network settings). page.authenticate() gives the page the “credentials for HTTP authentication” (Puppeteer, Page.authenticate); call it on every new page, before the first goto. Reading the login from environment variables keeps it out of your code. On a Linux server without unprivileged user namespaces, Chrome also needs --no-sandbox to start, as ours did.

What a wrong login looks like

Without page.authenticate(), or with a wrong password, page.goto throws:

net::ERR_INVALID_AUTH_CREDENTIALS at https://api.ipify.org

That is Chrome’s word for the proxy’s 407 Proxy Authentication Required: fix the login, not the page.

SOCKS5 needs a proxy without a password

Chrome cannot send a username and password to a SOCKS5 proxy. With --proxy-server=socks5://... and page.authenticate(), our run failed with:

net::ERR_SOCKS_CONNECTION_FAILED at https://api.ipify.org

Use the provider’s HTTP port with a login instead, or SOCKS5 with IP allowlisting (the proxy accepts your server’s address without a password; username and password vs IP whitelist).

One proxy per browser

--proxy-server applies to the whole browser, every page and tab. To send pages through different exits, launch one browser per proxy, or use a rotating gateway that changes the exit behind one address. page.authenticate() turns on request interception “behind the scenes”, which “might affect performance” (Puppeteer documentation), so measure a large job with it on.

What a browser costs in traffic

A headless browser downloads everything a page loads: images, scripts, fonts and ads, not only the HTML. On a plan billed by the GB, that can be many times the traffic of the same page loaded with Python Requests. Block images and media with request interception if your job does not need them, and check the size of a few pages first: how much bandwidth web scraping uses.

Next

Check the setup with how to test a proxy. The same browser driven by Selenium.