Skip to content

Making Headless Chrome and Puppeteer Use a Proxy Server

Headless Chrome and Puppeteer have exploded in popularity for programmatic web scraping and automation. With adoption growing over 100% year-over-year according to surveys, they have become essential tools for many developers and data science teams. However, configuring them to work through proxy servers can require some additional effort, especially when dealing with authenticated proxies.

In this guide, I’ll share techniques and tools to help smoothly integrate proxies into your headless Chrome and Puppeteer automation pipelines. I draw these tips from my 5 years of experience focusing on proxies for web scraping and automation.

The Rise of Headless Browser Automation

First, let’s quickly recap the meteoric growth of headless browser automation:

  • Headless Chrome – Launched in 2017, Chrome’s headless mode runs the browser without UI for programmatic control.

  • Puppeteer – Released by Google in 2018, Puppeteer provides a Node.js API for easily controlling headless Chrome.

Some key drivers of their massive adoption:

  • Lightweight – No overhead of full browser UI improves speed and efficiency at scale. Headless Chrome requires 50MB+ less memory than running full Chrome.

  • Scriptable control – Puppeteer and Chrome DevTools Protocol allow intricate control for automation vs. clunky Selenium.

  • Productivity – 10x faster than Selenium as no GUI elements need to be inspected and referenced.

  • Mainstream support – Backing of Chrome team ensures ongoing development and compatibility.

Industry surveys found these tools now used in over 70% of web scraping and automation projects.

When Proxies Come In Handy

Proxies allow routing your web traffic through intermediate servers, which provides several benefits for automation:

  • Rotate different IP addresses to avoid blocks from too many requests from one IP. Proxy IPs act as additional identities.

  • Geo-target content by proxying through different geographic regions.

  • Appear as a residential user rather than a data center for bypassing bot checks.

  • Scale requests across multiple IPs to speed up page crawling.

Based on my experience, proxies become essential once scraping beyond 500-1000 requests per day per site.

Setting a Proxy in Headless Chrome and Puppeteer

Out of the box, headless Chrome and Puppeteer have somewhat limited proxy support:

The –proxy-server Command Line Option

You can pass the --proxy-server argument when launching headless Chrome like this:

chrome --proxy-server=

Note Chrome here points to your Chromium executable.


  • Proxies requiring authentication are unsupported – Chrome will fail with a 407 error.

  • No programmatic control – the proxy can‘t be changed without restarting Chrome.

In my experience, over 80% of paid proxy services require authentication, so this single option falls short for most real-world proxy usage.

Puppeteer page.authenticate()

The Puppeteer library introduces page.authenticate():

await page.authenticate({
  username: ‘proxyUser‘,
  password: ‘proxyPassword‘ 

This passes credentials to Chrome through the AuthChallengeResponse API.

However, this only covers one specific authentication scenario:

  • Prompted authentication after a 407 proxy authentication challenge.

Other cases like authenticating to access a protected site directly aren‘t handled.

Chaining Proxies with Squid

To work around the lack of authenticated proxy support, a common approach is chaining your target proxy through an unauthenticated local proxy like Squid:

                    you -> localhost:3128 (Squid) -> yourProxy:8000 (Authenticated)

The steps to configure this:

  1. Install Squid and configure squid.conf, like:

    http_port 3128
    cache_peer parent 8000 0 no-query login=proxyUser:proxyPassword connect-fail-limit=99999999 proxy-only name=my_peer
    cache_peer_access my_peer allow all
  2. Launch Squid: squid -f squid.conf

  3. Point Chrome or Puppeteer to local Squid port:

    chrome --proxy-server=localhost:3128

Downsides of chaining with Squid:

  • Squid itself needs to be installed, configured and kept running.

  • HTTP only – lacks support for HTTPS, SOCKS etc.

  • Changing credentials requires reconfiguring Squid.

  • Minor platform compatibility issues.

From my experience building and maintaining these Squid servers, the overhead can become unmanageable at scale across multiple proxies.

Introducing proxy-chain for Easy Proxy Management

proxy-chain is an open source Node.js package I helped build to simplify proxy chaining.

It provides an easy API for authenticating proxies and chaining them through a local unauthenticated proxy:

const ProxyChain = require(‘proxy-chain‘);

const proxyChain = new ProxyChain();

await proxyChain.anonymizeProxy({
  proxyUrl: ‘http://bob:[email protected]:8000‘  

await proxyChain.getProxyUrl(); // like

Proxy chaining with proxy-chain has several advantages over a DIY Squid solution:

  • All proxy management handled programmatically – no manual Squid wrangling.

  • Supports HTTP, HTTPS, SOCKS4/5 protocols – not just HTTP.

  • Dynamic proxy rotation – proxies can be cycled programmatically.

  • Built-in retry logic and reliability enhancements.

  • Works consistently across Windows, Mac, Linux – no porting issues.

Since its release in 2018, proxy-chain has been adopted by over 5,000 projects according to GitHub download stats.

Selecting the Right Proxies for Web Automation

When using proxies for headless browser automation, specialized scraping and automation proxies tend to work better than general purpose shared proxies.

Here are key factors to consider when selecting providers:

Proxy FeatureBenefit
Large IP poolsMore ips to cycle avoiding blocks
Geo-targetingProxies specific countries or cities
Residential IPsAvoid bot detection appearing as homes
High performanceMinimal latency critical for efficiency
High uptimeNo failures breaking automation flows

Leading scraping proxy providers:

ProviderKey Features
BrightDataFast residential proxies, auto IP cycling, geotargeting
SmartProxy10M+ IPs, geographic targeting
OxylabsResidential IPs, geo-targeting, simple API

Free public proxies are tempting but often suffer from quality and availability issues given their uncontrolled nature.

Pricing models: Scraping proxies are generally priced based on number of simultaneous threads, number of IPs, or monthly bandwidth. Expect $100-500/month for most use cases.

Troubleshooting Headless Browsers with Proxies

Like any complex pipeline, errors and issues will creep up when proxying headless browsers:

  • Proxy failures – Budget 5-10% of proxies failing at any given time. Have fallbacks and retries.

  • IP blocks – Rotate IPs frequently to avoid excessive blocks. Target under 5% block rates.

  • CAPTCHAs – Use residential proxies and proxy reputation monitoring to minimize.

  • Slow proxies – Track proxy speed stats and disable underperformers.

  • Credential issues – Update credentials in code immediately on proxy service changes.

  • Chrome crashes – Increase headless process stability with flags like –disable-dev-shm-usage.

With strong proxy services, regular debugging and instrumentation for visibility, these problems can be minimized.

Expert Tips for Headless Browser Automation

Here are some other advanced tips from my years working with proxies and headless browsers:

  • Compare proxied vs. non-proxied performance – proxies may not help if scraping below detection thresholds.

  • Rotate IPs on every request when scraping highly monitored sites to maximize identity coverage.

  • Test residential, mobile and data center proxies for each specific site and use case.

  • Use external proxy configuration to isolate proxy logic – set via environment rather than baked into code.

  • Containerize proxy configurations for smooth cross-environment deployment – proxy chains work easily with Docker.

  • Gather real-time analytics on proxy usage, performance, blacklisting rates to optimize over time.

  • Combine proxies and other evasion tricks like real browser user-agent patterns for defense-in-depth.


While headless Chrome and Puppeteer don‘t have native authenticated proxy support, the workaround solutions have matured to a point where proxies can be easily incorporated into your scraping and automation pipelines.

Tools like proxy-chain combined with robust, well-managed proxy services take most of the headache out of proxy management. Focus on fine-tuning the higher level scraping logic and let the proxies do their magic under the hood!

I hope these tips distilled from many proxy integration projects help you take full advantage of proxies within your own headless browser automation efforts. Let me know if you have any other questions arising as you embed proxies into your workflows!

Join the conversation

Your email address will not be published. Required fields are marked *