Skip to content

How to Use Proxies with Puppeteer and Playwright

Working proxy configuration for both libraries, including authentication, per-context proxies in Playwright, and the detection tells that get headless browsers blocked.

Topic
Guides
Published
Reading time
3 minutes
Written by
froxproxy Team

Both libraries support proxies, but they handle authentication very differently, and Playwright’s approach is considerably better if you need more than one proxy at a time.

Puppeteer

The proxy is a Chrome launch flag, so it applies to the whole browser:

javascript
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://HOST:PORT'],
});

const page = await browser.newPage();
await page.authenticate({ username: 'USER', password: 'PASS' });

await page.goto('https://api.ipify.org');
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();

Two things to note.

Credentials cannot go in the flag. --proxy-server=http://user:pass@host:port does not work: Chrome ignores the userinfo. You must call page.authenticate(), and on every page you create.

One proxy per browser. To use several proxies you launch several browsers, which is memory-hungry. Roughly 100–200 MB each, so a pool of twenty is several gigabytes.

For SOCKS5, note that Chrome cannot authenticate SOCKS proxies at all. Use IP whitelisting if you need SOCKS. See authentication methods.

Playwright

Playwright accepts credentials directly and, more usefully, supports a proxy per browser context:

javascript
import { chromium } from 'playwright';

const browser = await chromium.launch();

const context = await browser.newContext({
  proxy: {
    server:   'http://HOST:PORT',
    username: 'USER',
    password: 'PASS',
  },
});

const page = await context.newPage();
await page.goto('https://api.ipify.org');
console.log(await page.textContent('body'));
await browser.close();

Contexts are the reason to prefer Playwright here. Each is an isolated browser session, with its own cookies, storage and proxy, but they share one browser process. Ten contexts with ten proxies cost a fraction of ten browsers:

javascript
const proxies = [/* ... */];

const contexts = await Promise.all(
  proxies.map((p) =>
    browser.newContext({
      proxy: { server: p.server, username: p.user, password: p.pass },
    })
  )
);

That combination of isolated cookies and a dedicated IP per context is exactly what you want for managing multiple accounts. See proxies for social media.

Block images to cut bandwidth

On residential proxies you pay per gigabyte, and images are most of a page’s weight:

javascript
await page.route('**/*', (route) => {
  const type = route.request().resourceType();
  if (['image', 'media', 'font'].includes(type)) return route.abort();
  return route.continue();
});

This routinely cuts bandwidth by 70–80%. The trade-off is that a browser fetching no images is itself a signal. It is worth it for bulk work, not when you are trying hard to look human.

Puppeteer equivalent:

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

Headless browsers are detectable by default

A proxy hides your IP; it does nothing about the browser announcing itself as automated.

Out of the box, both libraries expose navigator.webdriver === true, ship a HeadlessChrome user agent, and have missing or inconsistent properties that detection scripts check routinely.

At minimum:

javascript
const context = await browser.newContext({
  proxy: { /* ... */ },
  userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' +
             '(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36',
  viewport: { width: 1920, height: 1080 },
  locale: 'en-GB',
  timezoneId: 'Europe/London',
});

Keep those consistent with the proxy. A German IP with en-US and America/New_York is a contradiction that fingerprinting catches immediately, and it is worse than leaving the defaults.

For the deeper tells, puppeteer-extra-plugin-stealth patches the well-known ones. It is not a complete answer against serious anti-bot systems, but it clears the easy checks. More on this in why proxies get banned.

Verify the proxy is actually in use

javascript
const ip = await page.evaluate(() =>
  fetch('https://api.ipify.org').then((r) => r.text())
);
console.log('exit IP:', ip);

If that matches your own address, the configuration is not taking effect. With Puppeteer this usually means the launch flag was malformed.

Which to choose

Playwright, unless you have a reason not to. Per-context proxies, credentials handled natively, and far lower memory when running several identities at once. Puppeteer is fine for a single proxy and a single session.

See pricing for proxy costs, or how many proxies you need for sizing.

Send your first request in the next five minutes.

Create an account, pick a plan, and get your proxies set up automatically after payment. No lock-in, and nothing renews unless you switch it on.

Pay with cards or crypto

  • Visa
  • Mastercard
  • Bitcoin
  • Ethereum
  • USDT

Opens chat from Tawk.to (US). It stores cookies in your browser. Cookie Policy