Skip to content
seamless

How to use proxies with Puppeteer

Puppeteer takes the proxy as a Chromium launch flag, --proxy-server, and handles credentials separately through page.authenticate(). Because the flag is process-wide, running several exit IPs means launching several browser instances.

Setup

Set up Puppeteer in 4 steps

  1. 01

    Install Puppeteer

    Install the package, which downloads a matching Chromium build.

    npm i puppeteer
  2. 02

    Launch with the proxy flag

    Pass the proxy as a Chromium argument. Credentials cannot go in this flag — they are supplied in the next step. Replace PROXY_HOST, PROXY_PORT, USERNAME and PASSWORD with the endpoint and credentials shown in your seamless dashboard.

    const puppeteer = require("puppeteer");
    
    const browser = await puppeteer.launch({
      args: ["--proxy-server=http://PROXY_HOST:PROXY_PORT"],
    });
  3. 03

    Authenticate the page

    Call page.authenticate() before the first navigation, otherwise Chromium answers the proxy's auth challenge with nothing and the request fails.

    const page = await browser.newPage();
    await page.authenticate({ username: "USERNAME", password: "PASSWORD" });
    await page.goto("https://example.com", { waitUntil: "domcontentloaded" });
  4. 04

    Cut bandwidth by blocking assets

    Residential proxies are billed per gigabyte and a rendered page pulls in images, fonts and trackers you almost never need. Blocking them routinely cuts consumption by an order of magnitude.

    await page.setRequestInterception(true);
    page.on("request", (req) => {
      const blocked = ["image", "font", "media", "stylesheet"];
      blocked.includes(req.resourceType()) ? req.abort() : req.continue();
    });

FAQ

Questions about Puppeteer proxies

Anything else? Our team answers on live chat, by email and on Discord.

How do I use an authenticated proxy with Puppeteer?

Pass the host and port with --proxy-server at launch, then call page.authenticate({ username, password }) on each page before navigating. Credentials in the --proxy-server URL are ignored by Chromium.

Can Puppeteer use a different proxy per page?

No. --proxy-server is a browser-level flag, so every page in a browser instance shares it. To use several exit IPs at once, launch one browser per proxy, or switch to Playwright, which supports per-context proxies.

How do I reduce proxy bandwidth in Puppeteer?

Enable request interception and abort image, font, media and stylesheet requests. On image-heavy sites this often reduces bandwidth by 80% or more, which directly reduces what you pay per page.

Start small. Scale when it works.

Buy a little bandwidth or rent a single ISP proxy for a day, test it on your own targets, then grow from there.