Geonode logo
Developer, scraping & anti-detect tools

Puppeteer Proxy Set It for the Whole Browser or for Each Context

Get residential proxies for PuppeteerCheck free proxies

Puppeteer works on

  • Windows
  • macOS
  • Linux

Key facts

  • How to set it

    Put --proxy-server=http://HOST:PORT in the launch args, then call page.authenticate({ username, password }) before page.goto().

  • Login turns on interception

    page.authenticate() works by turning on request interception, and the Puppeteer docs warn that this might affect performance.

  • DNS goes through SOCKS5

    With a socks5:// proxy, Chrome always resolves hostnames on the proxy side. DNS lookups for your target sites never leave from your own network.

Ways to connect Puppeteer to a proxy

Puppeteer hands the proxy to the Chrome it launches, so Chrome's proxy rules decide what works. These steps are for Chrome. With browser: 'firefox', Firefox ignores Chrome flags like --proxy-server, so set the proxy through extraPrefsFirefox with Firefox's network.proxy.* prefs.

NameWorks InAuthBlocking ResistanceBest ForWhere To Get
HTTP proxy in --proxy-serverChrome and Chrome for Testing launched by Puppeteer, headless or headfulUsername and password through page.authenticate() on each pageSet by the IP type (residential, ISP or datacenter)Most scraping and testing with a username:password proxyGeonode residential, ISP or datacenter proxies; Geonode free list
SOCKS5 in --proxy-serverChrome launched by PuppeteerNone: Chrome supports no SOCKS5 authentication, so the proxy must accept your IP without a loginSame as HTTPSOCKS5 proxies without a passwordGeonode free list (SOCKS5 entries)
proxyServer in createBrowserContext()Chrome launched by Puppeteer; each browser context gets its own proxypage.authenticate() on each page in the contextSame as HTTPSeveral proxies or sticky sessions inside one browser processGeonode residential, ISP or datacenter proxies
System proxy (Windows or macOS settings)Chrome launched without --proxy-server; also changes every other app that follows the system proxypage.authenticate() answers the HTTP proxy loginSame as HTTPQuick checks on one machine; not for servers or parallel jobsGeonode residential, ISP or datacenter proxies; Geonode free list

Which proxy type to use with Puppeteer

Target sites judge the exit IP and the request rate. Many sites forbid automated access in their terms and block or ban accounts they catch, and a proxy lowers the chance of a block without removing it.

Best for Puppeteer

Residential proxies

from $0.27/GB

Residential IPs belong to home connections, and sites with bot protection block them far less often than datacenter ranges. When a login has to survive several pages, a sticky session holds one IP for up to 24 hours.

Start $5 trialSee residential pricing
Logged-in automation

ISP proxies

from $1.25/IP

You keep the same IP for as long as you rent it. A script that signs in to one account every day always connects from that address.

See ISP pricing
Unprotected sites, tests

Datacenter proxies

from $0.14/GB

Datacenter IPs are cheap per GB and fast, which is fine for end-to-end tests and sites without bot protection. Protected sites flag these ranges first.

See datacenter pricing
Testing only

Free public proxies

Free

Free proxies are shared and often already blocked. Use one only to check that your launch args and error handling work.

Get free proxies

How to set up a proxy for Puppeteer

Get the proxy host, port and protocol from your provider's dashboard, plus the proxy username and password.

  1. Install Puppeteer with npm i puppeteer. It downloads a matching Chrome for Testing.

  2. Copy the host, port, username and password of an HTTP proxy from the Geonode dashboard.

  3. Launch with the proxy in args: puppeteer.launch({ args: ['--proxy-server=http://HOST:PORT'] }).

  4. Keep the username and password out of the flag. Chrome does not read them there.

  5. Open a tab with const page = await browser.newPage().

  6. Call await page.authenticate({ username: 'USER', password: 'PASS' }) before page.goto().

  7. Call page.authenticate() again on every new page you open.

  8. For a SOCKS5 proxy without a login, use --proxy-server=socks5://HOST:PORT.

Check detailed instructions on our blog:

Read the blog post

How to check that the proxy works

  1. Open https://api.ipify.org with page.goto() and print await page.evaluate(() => document.body.innerText).

  2. Compare the result with your own IP on the Geonode What is my IP page in a normal browser. They must differ.

  3. Launch with headless: false once to watch the page load and catch any proxy error page.

How to turn the proxy off

  1. Remove --proxy-server from args, or proxyServer from createBrowserContext(), and relaunch.

  2. Call await page.authenticate(null) to stop sending the login and turn off the interception it enabled.

  3. Add --no-proxy-server to args if Chrome should also ignore the system proxy.

Common Puppeteer proxy problems and fixes

  • page.goto() fails with invalid proxy credentials or a 407

    Cause
    Puppeteer throws net::ERR_INVALID_AUTH_CREDENTIALS when page.authenticate() was not called on that page, was called after page.goto(), or the credentials are wrong
    Fix
    Follow the page.authenticate() step in the setup. Use the proxy username and password from the Geonode dashboard, not your account login.

  • A SOCKS5 proxy with a login never connects

    Cause
    The proxy expects a SOCKS5 login, and Chrome never sends one
    Fix
    Switch to the HTTP port of the same proxy, or run a local forwarder with the proxy-chain npm package: const url = await anonymizeProxy('socks5://USER:PASS@HOST:PORT'), then pass --proxy-server=${url}. Call closeAnonymizedProxy(url, true) when done.

  • page.goto() fails with a proxy or tunnel connection error

    Cause
    Puppeteer throws net::ERR_PROXY_CONNECTION_FAILED or net::ERR_TUNNEL_CONNECTION_FAILED. Wrong host or port, a scheme that does not match the port, or a firewall that blocks outbound traffic to the proxy port
    Fix
    Check that the scheme (http:// or socks5://) matches the port your provider lists. Then test the same proxy in the Geonode proxy checker. If it fails there too, fix the proxy before you debug the script.

  • Requests to localhost or 127.0.0.1 skip the proxy

    Cause
    Chrome never sends localhost and loopback requests through a proxy
    Fix
    Add --proxy-bypass-list=<-loopback> to the launch args if you test a local server through the proxy.

  • The site returns 403, 429 or a CAPTCHA through the proxy

    Cause
    The site flags the IP range, or too many requests come from one sticky IP
    Fix
    Move to residential IPs and use a rotating session for pages that need no login. Also open fewer pages in parallel.

More for Puppeteer users

Puppeteer proxy FAQ

Add --proxy-server=http://HOST:PORT to the launch args. Then call page.authenticate() with the proxy username and password before page.goto(), and every request from that browser goes through the proxy.

Call await page.authenticate({ username, password }) on each page before it navigates. Chrome ignores a username and password written inside the --proxy-server value.

Yes, with --proxy-server=socks5://HOST:PORT, but only for SOCKS5 proxies without a login, because Chrome supports no SOCKS5 authentication. For a proxy that needs a password, use its HTTP port.

Per browser context, yes. browser.createBrowserContext({ proxyServer }) gives each context its own proxy, cookies and cache, so open one context per proxy and create its pages there.

puppeteer-proxy and puppeteer-page-proxy are npm packages that set a proxy per page or per request. They intercept each request and send it again from Node.js through the proxy, so Chrome itself never connects to the site. That is slower than a browser-level proxy. If one proxy per browser context is enough, createBrowserContext({ proxyServer }) needs no extra package.

Point Puppeteer at a rotating residential gateway, which changes the exit IP on the provider side without a relaunch. To control rotation yourself, create a new browser context with a different proxyServer for each batch of pages.

Residential proxies, if the site has bot protection, because those sites block datacenter ranges first. For test suites and sites that don't check the IP type, datacenter proxies are enough.